Merge 5e841f9cac into 6eb7c34752

docs: update test-design workflow to generate two documents for system-level mode (#1367 )
* docs: update test-design workflow to generate two documents for system-level mode * addressed pr comments
2026-01-22 21:35:17 -05:00 · 2026-01-22 14:29:33 -06:00 · 2026-01-08 11:46:12 -05:00
35 changed files with 6859 additions and 105 deletions
--- a/docs/explanation/features/tea-overview.md
+++ b/docs/explanation/features/tea-overview.md
@ -160,7 +160,7 @@ graph TB

 **TEA workflows:** `*framework` and `*ci` run once in Phase 3 after architecture. `*test-design` is **dual-mode**:

- **System-level (Phase 3):** Run immediately after architecture/ADR drafting to produce `test-design-system.md` (testability review, ADR → test mapping, Architecturally Significant Requirements (ASRs), environment needs). Feeds the implementation-readiness gate.
+- **System-level (Phase 3):** Run immediately after architecture/ADR drafting to produce TWO documents: `test-design-architecture.md` (for Architecture/Dev teams: testability gaps, ASRs, NFR requirements) + `test-design-qa.md` (for QA team: test execution recipe, coverage plan, Sprint 0 setup). Feeds the implementation-readiness gate.
 - **Epic-level (Phase 4):** Run per-epic to produce `test-design-epic-N.md` (risk, priorities, coverage plan).

 The Quick Flow track skips Phases 1 and 3.
--- a/docs/how-to/brownfield/use-tea-for-enterprise.md
+++ b/docs/how-to/brownfield/use-tea-for-enterprise.md
@ -114,10 +114,9 @@ Focus areas:
 - Performance requirements (SLA: P99 <200ms)
 - Compliance (HIPAA PHI handling, audit logging)

-Output: test-design-system.md with:
- Security testing strategy
- Compliance requirement → test mapping
- Performance testing plan
+Output: TWO documents (system-level):
+- `test-design-architecture.md`: Security gaps, compliance requirements, performance SLOs for Architecture team
+- `test-design-qa.md`: Security testing strategy, compliance test mapping, performance testing plan for QA team
 - Audit logging validation
 ```

--- a/docs/how-to/workflows/run-test-design.md
+++ b/docs/how-to/workflows/run-test-design.md
@ -55,20 +55,44 @@ For epic-level:

 ### 5. Review the Output

-TEA generates a comprehensive test design document.
+TEA generates test design document(s) based on mode.

 ## What You Get

-**System-Level Output (`test-design-system.md`):**
- Testability review of architecture
- ADR → test mapping
- Architecturally Significant Requirements (ASRs)
- Environment needs
- Test infrastructure recommendations
+**System-Level Output (TWO Documents):**

-**Epic-Level Output (`test-design-epic-N.md`):**
+TEA produces two focused documents for system-level mode:
+
+1. **`test-design-architecture.md`** (for Architecture/Dev teams)
+   - Purpose: Architectural concerns, testability gaps, NFR requirements
+   - Quick Guide with 🚨 BLOCKERS / ⚠️ HIGH PRIORITY / 📋 INFO ONLY
+   - Risk assessment (high/medium/low-priority with scoring)
+   - Testability concerns and architectural gaps
+   - Risk mitigation plans for high-priority risks (≥6)
+   - Assumptions and dependencies
+
+2. **`test-design-qa.md`** (for QA team)
+   - Purpose: Test execution recipe, coverage plan, Sprint 0 setup
+   - Quick Reference for QA (Before You Start, Execution Order, Need Help)
+   - System architecture summary
+   - Test environment requirements (moved up - early in doc)
+   - Testability assessment (prerequisites checklist)
+   - Test levels strategy (unit/integration/E2E split)
+   - Test coverage plan (P0/P1/P2/P3 with detailed scenarios + checkboxes)
+   - Sprint 0 setup requirements (blockers, infrastructure, environments)
+   - NFR readiness summary
+
+**Why Two Documents?**
+- **Architecture teams** can scan blockers in <5 min (Quick Guide format)
+- **QA teams** have actionable test recipes (step-by-step with checklists)
+- **No redundancy** between documents (cross-references instead of duplication)
+- **Clear separation** of concerns (what to deliver vs how to test)
+
+**Epic-Level Output (ONE Document):**
+
+**`test-design-epic-N.md`** (combined risk assessment + test plan)
 - Risk assessment for the epic
- Test priorities
+- Test priorities (P0-P3)
 - Coverage plan
 - Regression hotspots (for brownfield)
 - Integration risks
@ -82,12 +106,25 @@ TEA generates a comprehensive test design document.
 | **Brownfield** | System-level + existing test baseline | Regression hotspots, integration risks |
 | **Enterprise** | Compliance-aware testability | Security/performance/compliance focus |

+## Examples
+
+**System-Level (Two Documents):**
+- `cluster-search/cluster-search-test-design-architecture.md` - Architecture doc with Quick Guide
+- `cluster-search/cluster-search-test-design-qa.md` - QA doc with test scenarios
+
+**Key Pattern:**
+- Architecture doc: "ASR-1: OAuth 2.1 required (see QA doc for 12 test scenarios)"
+- QA doc: "OAuth tests: 12 P0 scenarios (see Architecture doc R-001 for risk details)"
+- No duplication, just cross-references
+
 ## Tips

 - **Run system-level right after architecture** — Early testability review
 - **Run epic-level at the start of each epic** — Targeted test planning
 - **Update if ADRs change** — Keep test design aligned
 - **Use output to guide other workflows** — Feeds into `*atdd` and `*automate`
+- **Architecture teams review Architecture doc** — Focus on blockers and mitigation plans
+- **QA teams use QA doc as implementation guide** — Follow test scenarios and Sprint 0 checklist

 ## Next Steps

--- a/docs/reference/tea/commands.md
+++ b/docs/reference/tea/commands.md
@ -72,17 +72,39 @@ Quick reference for all 8 TEA (Test Architect) workflows. For detailed step-by-s
 **Frequency:** Once (system), per epic (epic-level)

 **Modes:**
- **System-level:** Architecture testability review
- **Epic-level:** Per-epic risk assessment
+- **System-level:** Architecture testability review (TWO documents)
+- **Epic-level:** Per-epic risk assessment (ONE document)

 **Key Inputs:**
- Architecture/epic, requirements, ADRs
+- System-level: Architecture, PRD, ADRs
+- Epic-level: Epic, stories, acceptance criteria

 **Key Outputs:**
- `test-design-system.md` or `test-design-epic-N.md`
- Risk assessment (probability × impact scores)
- Test priorities (P0-P3)
- Coverage strategy
+
+**System-Level (TWO Documents):**
+- `test-design-architecture.md` - For Architecture/Dev teams
+  - Quick Guide (🚨 BLOCKERS / ⚠️ HIGH PRIORITY / 📋 INFO ONLY)
+  - Risk assessment with scoring
+  - Testability concerns and gaps
+  - Mitigation plans
+- `test-design-qa.md` - For QA team
+  - Test execution recipe
+  - Coverage plan (P0/P1/P2/P3 with checkboxes)
+  - Sprint 0 setup requirements
+  - NFR readiness summary
+
+**Epic-Level (ONE Document):**
+- `test-design-epic-N.md`
+  - Risk assessment (probability × impact scores)
+  - Test priorities (P0-P3)
+  - Coverage strategy
+  - Mitigation plans
+
+**Why Two Documents for System-Level?**
+- Architecture teams scan blockers in <5 min
+- QA teams have actionable test recipes
+- No redundancy (cross-references instead)
+- Clear separation (what to deliver vs how to test)

 **MCP Enhancement:** Exploratory mode (live browser UI discovery)

--- a/docs/reference/tea/configuration.md
+++ b/docs/reference/tea/configuration.md
@ -197,7 +197,7 @@ output_folder: _bmad-output
 ```

 **TEA Output Files:**
- `test-design-system.md` (from *test-design system-level)
+- `test-design-architecture.md` + `test-design-qa.md` (from *test-design system-level - TWO documents)
 - `test-design-epic-N.md` (from *test-design epic-level)
 - `test-review.md` (from *test-review)
 - `traceability-matrix.md` (from *trace Phase 1)
--- a/docs/tutorials/getting-started/tea-lite-quickstart.md
+++ b/docs/tutorials/getting-started/tea-lite-quickstart.md
@ -15,7 +15,7 @@ By the end of this 30-minute tutorial, you'll have:
 :::note[Prerequisites]
 - Node.js installed (v20 or later)
 - 30 minutes of focused time
- We'll use TodoMVC (<https://todomvc.com/examples/react/>) as our demo app
+- We'll use TodoMVC (<https://todomvc.com/examples/react/dist/>) as our demo app
 :::

 :::tip[Quick Path]
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@ -81,6 +81,21 @@ export default [
    },
  },

+  // Test files using Vitest (ES modules)
+  {
+    files: ['test/unit/**/*.js', 'test/integration/**/*.js', 'test/helpers/**/*.js', 'test/setup.js', 'vitest.config.js'],
+    languageOptions: {
+      sourceType: 'module',
+      ecmaVersion: 'latest',
+    },
+    rules: {
+      // Allow dev dependencies in test files
+      'n/no-unpublished-import': 'off',
+      'unicorn/prefer-module': 'off',
+      'no-unused-vars': 'off',
+    },
+  },
+
  // CLI scripts under tools/** and test/**
  {
    files: ['tools/**/*.js', 'tools/**/*.mjs', 'test/**/*.js'],
--- a/package-lock.json
+++ b/package-lock.json
@ -35,6 +35,8 @@
        "@astrojs/sitemap": "^3.6.0",
        "@astrojs/starlight": "^0.37.0",
        "@eslint/js": "^9.33.0",
+        "@vitest/coverage-v8": "^4.0.16",
+        "@vitest/ui": "^4.0.16",
        "archiver": "^7.0.1",
        "astro": "^5.16.0",
        "c8": "^10.1.3",
@ -50,6 +52,7 @@
        "prettier": "^3.7.4",
        "prettier-plugin-packagejson": "^2.5.19",
        "sharp": "^0.33.5",
+        "vitest": "^4.0.16",
        "yaml-eslint-parser": "^1.2.3",
        "yaml-lint": "^1.7.0"
      },
@ -2983,6 +2986,13 @@
        "url": "https://opencollective.com/pkgr"
      }
    },
+    "node_modules/@polka/url": {
+      "version": "1.0.0-next.29",
+      "resolved": "https://registry.npmjs.org/@polka/url/-/url-1.0.0-next.29.tgz",
+      "integrity": "sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@rollup/pluginutils": {
      "version": "5.3.0",
      "resolved": "https://registry.npmjs.org/@rollup/pluginutils/-/pluginutils-5.3.0.tgz",
@ -3435,6 +3445,13 @@
        "@sinonjs/commons": "^3.0.1"
      }
    },
+    "node_modules/@standard-schema/spec": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.1.0.tgz",
+      "integrity": "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@swc/helpers": {
      "version": "0.5.18",
      "resolved": "https://registry.npmjs.org/@swc/helpers/-/helpers-0.5.18.tgz",
@ -3501,6 +3518,17 @@
        "@babel/types": "^7.28.2"
      }
    },
+    "node_modules/@types/chai": {
+      "version": "5.2.3",
+      "resolved": "https://registry.npmjs.org/@types/chai/-/chai-5.2.3.tgz",
+      "integrity": "sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/deep-eql": "*",
+        "assertion-error": "^2.0.1"
+      }
+    },
    "node_modules/@types/debug": {
      "version": "4.1.12",
      "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
@ -3510,6 +3538,13 @@
        "@types/ms": "*"
      }
    },
+    "node_modules/@types/deep-eql": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/@types/deep-eql/-/deep-eql-4.0.2.tgz",
+      "integrity": "sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/@types/estree": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz",
@ -3953,6 +3988,171 @@
        "win32"
      ]
    },
+    "node_modules/@vitest/coverage-v8": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.0.16.tgz",
+      "integrity": "sha512-2rNdjEIsPRzsdu6/9Eq0AYAzYdpP6Bx9cje9tL3FE5XzXRQF1fNU9pe/1yE8fCrS0HD+fBtt6gLPh6LI57tX7A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.2",
+        "@vitest/utils": "4.0.16",
+        "ast-v8-to-istanbul": "^0.3.8",
+        "istanbul-lib-coverage": "^3.2.2",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-lib-source-maps": "^5.0.6",
+        "istanbul-reports": "^3.2.0",
+        "magicast": "^0.5.1",
+        "obug": "^2.1.1",
+        "std-env": "^3.10.0",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@vitest/browser": "4.0.16",
+        "vitest": "4.0.16"
+      },
+      "peerDependenciesMeta": {
+        "@vitest/browser": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/expect": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/expect/-/expect-4.0.16.tgz",
+      "integrity": "sha512-eshqULT2It7McaJkQGLkPjPjNph+uevROGuIMJdG3V+0BSR2w9u6J9Lwu+E8cK5TETlfou8GRijhafIMhXsimA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@standard-schema/spec": "^1.0.0",
+        "@types/chai": "^5.2.2",
+        "@vitest/spy": "4.0.16",
+        "@vitest/utils": "4.0.16",
+        "chai": "^6.2.1",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/mocker": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/mocker/-/mocker-4.0.16.tgz",
+      "integrity": "sha512-yb6k4AZxJTB+q9ycAvsoxGn+j/po0UaPgajllBgt1PzoMAAmJGYFdDk0uCcRcxb3BrME34I6u8gHZTQlkqSZpg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/spy": "4.0.16",
+        "estree-walker": "^3.0.3",
+        "magic-string": "^0.30.21"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "msw": "^2.4.9",
+        "vite": "^6.0.0 || ^7.0.0-0"
+      },
+      "peerDependenciesMeta": {
+        "msw": {
+          "optional": true
+        },
+        "vite": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/@vitest/pretty-format": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/pretty-format/-/pretty-format-4.0.16.tgz",
+      "integrity": "sha512-eNCYNsSty9xJKi/UdVD8Ou16alu7AYiS2fCPRs0b1OdhJiV89buAXQLpTbe+X8V9L6qrs9CqyvU7OaAopJYPsA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/runner": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/runner/-/runner-4.0.16.tgz",
+      "integrity": "sha512-VWEDm5Wv9xEo80ctjORcTQRJ539EGPB3Pb9ApvVRAY1U/WkHXmmYISqU5E79uCwcW7xYUV38gwZD+RV755fu3Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.0.16",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/snapshot": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/snapshot/-/snapshot-4.0.16.tgz",
+      "integrity": "sha512-sf6NcrYhYBsSYefxnry+DR8n3UV4xWZwWxYbCJUt2YdvtqzSPR7VfGrY0zsv090DAbjFZsi7ZaMi1KnSRyK1XA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.16",
+        "magic-string": "^0.30.21",
+        "pathe": "^2.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/spy": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/spy/-/spy-4.0.16.tgz",
+      "integrity": "sha512-4jIOWjKP0ZUaEmJm00E0cOBLU+5WE0BpeNr3XN6TEF05ltro6NJqHWxXD0kA8/Zc8Nh23AT8WQxwNG+WeROupw==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
+    "node_modules/@vitest/ui": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/ui/-/ui-4.0.16.tgz",
+      "integrity": "sha512-rkoPH+RqWopVxDnCBE/ysIdfQ2A7j1eDmW8tCxxrR9nnFBa9jKf86VgsSAzxBd1x+ny0GC4JgiD3SNfRHv3pOg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/utils": "4.0.16",
+        "fflate": "^0.8.2",
+        "flatted": "^3.3.3",
+        "pathe": "^2.0.3",
+        "sirv": "^3.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "vitest": "4.0.16"
+      }
+    },
+    "node_modules/@vitest/utils": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/@vitest/utils/-/utils-4.0.16.tgz",
+      "integrity": "sha512-h8z9yYhV3e1LEfaQ3zdypIrnAg/9hguReGZoS7Gl0aBG5xgA410zBqECqmaF/+RkTggRsfnzc1XaAHA6bmUufA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/pretty-format": "4.0.16",
+        "tinyrainbow": "^3.0.3"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      }
+    },
    "node_modules/abort-controller": {
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/abort-controller/-/abort-controller-3.0.0.tgz",
@ -4264,6 +4464,35 @@
        "node": ">=8"
      }
    },
+    "node_modules/assertion-error": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-2.0.1.tgz",
+      "integrity": "sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/ast-v8-to-istanbul": {
+      "version": "0.3.10",
+      "resolved": "https://registry.npmjs.org/ast-v8-to-istanbul/-/ast-v8-to-istanbul-0.3.10.tgz",
+      "integrity": "sha512-p4K7vMz2ZSk3wN8l5o3y2bJAoZXT3VuJI5OLTATY/01CYWumWvwkUw0SqDBnNq6IiTO3qDa1eSQDibAV8g7XOQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.31",
+        "estree-walker": "^3.0.3",
+        "js-tokens": "^9.0.1"
+      }
+    },
+    "node_modules/ast-v8-to-istanbul/node_modules/js-tokens": {
+      "version": "9.0.1",
+      "resolved": "https://registry.npmjs.org/js-tokens/-/js-tokens-9.0.1.tgz",
+      "integrity": "sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/astring": {
      "version": "1.9.0",
      "resolved": "https://registry.npmjs.org/astring/-/astring-1.9.0.tgz",
@ -5513,6 +5742,16 @@
        "url": "https://github.com/sponsors/wooorm"
      }
    },
+    "node_modules/chai": {
+      "version": "6.2.2",
+      "resolved": "https://registry.npmjs.org/chai/-/chai-6.2.2.tgz",
+      "integrity": "sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/chalk": {
      "version": "4.1.2",
      "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
@ -7248,6 +7487,16 @@
        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
      }
    },
+    "node_modules/expect-type": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.3.0.tgz",
+      "integrity": "sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=12.0.0"
+      }
+    },
    "node_modules/expressive-code": {
      "version": "0.41.5",
      "resolved": "https://registry.npmjs.org/expressive-code/-/expressive-code-0.41.5.tgz",
@ -7363,6 +7612,13 @@
        }
      }
    },
+    "node_modules/fflate": {
+      "version": "0.8.2",
+      "resolved": "https://registry.npmjs.org/fflate/-/fflate-0.8.2.tgz",
+      "integrity": "sha512-cPJU47OaAoCbg0pBvzsgpTPhmhqI5eJjh/JIu8tPj5q+T7iLvW/JAYUqmE7KOB4R1ZyEhzBaIQpQpardBF5z8A==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/figlet": {
      "version": "1.9.4",
      "resolved": "https://registry.npmjs.org/figlet/-/figlet-1.9.4.tgz",
@ -11693,6 +11949,17 @@
        "url": "https://github.com/fb55/nth-check?sponsor=1"
      }
    },
+    "node_modules/obug": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/obug/-/obug-2.1.1.tgz",
+      "integrity": "sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==",
+      "dev": true,
+      "funding": [
+        "https://github.com/sponsors/sxzz",
+        "https://opencollective.com/debug"
+      ],
+      "license": "MIT"
+    },
    "node_modules/ofetch": {
      "version": "1.5.1",
      "resolved": "https://registry.npmjs.org/ofetch/-/ofetch-1.5.1.tgz",
@ -12138,6 +12405,13 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/pathe": {
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/pathe/-/pathe-2.0.3.tgz",
+      "integrity": "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/piccolore": {
      "version": "0.1.3",
      "resolved": "https://registry.npmjs.org/piccolore/-/piccolore-0.1.3.tgz",
@ -13362,6 +13636,13 @@
        "@types/hast": "^3.0.4"
      }
    },
+    "node_modules/siginfo": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/siginfo/-/siginfo-2.0.0.tgz",
+      "integrity": "sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==",
+      "dev": true,
+      "license": "ISC"
+    },
    "node_modules/signal-exit": {
      "version": "4.1.0",
      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
@ -13391,6 +13672,21 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/sirv": {
+      "version": "3.0.2",
+      "resolved": "https://registry.npmjs.org/sirv/-/sirv-3.0.2.tgz",
+      "integrity": "sha512-2wcC/oGxHis/BoHkkPwldgiPSYcpZK3JU28WoMVv55yHJgcZ8rlXvuG9iZggz+sU1d4bRgIGASwyWqjxu3FM0g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@polka/url": "^1.0.0-next.24",
+        "mrmime": "^2.0.0",
+        "totalist": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
    "node_modules/sisteransi": {
      "version": "1.0.5",
      "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",
@ -13601,6 +13897,20 @@
        "node": ">=8"
      }
    },
+    "node_modules/stackback": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/stackback/-/stackback-0.0.2.tgz",
+      "integrity": "sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/std-env": {
+      "version": "3.10.0",
+      "resolved": "https://registry.npmjs.org/std-env/-/std-env-3.10.0.tgz",
+      "integrity": "sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/stream-replace-string": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/stream-replace-string/-/stream-replace-string-2.0.0.tgz",
@ -14015,6 +14325,13 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/tinybench": {
+      "version": "2.9.0",
+      "resolved": "https://registry.npmjs.org/tinybench/-/tinybench-2.9.0.tgz",
+      "integrity": "sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==",
+      "dev": true,
+      "license": "MIT"
+    },
    "node_modules/tinyexec": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.2.tgz",
@ -14042,6 +14359,16 @@
        "url": "https://github.com/sponsors/SuperchupuDev"
      }
    },
+    "node_modules/tinyrainbow": {
+      "version": "3.0.3",
+      "resolved": "https://registry.npmjs.org/tinyrainbow/-/tinyrainbow-3.0.3.tgz",
+      "integrity": "sha512-PSkbLUoxOFRzJYjjxHJt9xro7D+iilgMX/C9lawzVuYiIdcihh9DXmVibBe8lmcFrRi/VzlPjBxbN7rH24q8/Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.0.0"
+      }
+    },
    "node_modules/tmpl": {
      "version": "1.0.5",
      "resolved": "https://registry.npmjs.org/tmpl/-/tmpl-1.0.5.tgz",
@ -14062,6 +14389,16 @@
        "node": ">=8.0"
      }
    },
+    "node_modules/totalist": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/totalist/-/totalist-3.0.1.tgz",
+      "integrity": "sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
    "node_modules/trim-lines": {
      "version": "3.0.1",
      "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz",
@ -14807,6 +15144,84 @@
        }
      }
    },
+    "node_modules/vitest": {
+      "version": "4.0.16",
+      "resolved": "https://registry.npmjs.org/vitest/-/vitest-4.0.16.tgz",
+      "integrity": "sha512-E4t7DJ9pESL6E3I8nFjPa4xGUd3PmiWDLsDztS2qXSJWfHtbQnwAWylaBvSNY48I3vr8PTqIZlyK8TE3V3CA4Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@vitest/expect": "4.0.16",
+        "@vitest/mocker": "4.0.16",
+        "@vitest/pretty-format": "4.0.16",
+        "@vitest/runner": "4.0.16",
+        "@vitest/snapshot": "4.0.16",
+        "@vitest/spy": "4.0.16",
+        "@vitest/utils": "4.0.16",
+        "es-module-lexer": "^1.7.0",
+        "expect-type": "^1.2.2",
+        "magic-string": "^0.30.21",
+        "obug": "^2.1.1",
+        "pathe": "^2.0.3",
+        "picomatch": "^4.0.3",
+        "std-env": "^3.10.0",
+        "tinybench": "^2.9.0",
+        "tinyexec": "^1.0.2",
+        "tinyglobby": "^0.2.15",
+        "tinyrainbow": "^3.0.3",
+        "vite": "^6.0.0 || ^7.0.0",
+        "why-is-node-running": "^2.3.0"
+      },
+      "bin": {
+        "vitest": "vitest.mjs"
+      },
+      "engines": {
+        "node": "^20.0.0 || ^22.0.0 || >=24.0.0"
+      },
+      "funding": {
+        "url": "https://opencollective.com/vitest"
+      },
+      "peerDependencies": {
+        "@edge-runtime/vm": "*",
+        "@opentelemetry/api": "^1.9.0",
+        "@types/node": "^20.0.0 || ^22.0.0 || >=24.0.0",
+        "@vitest/browser-playwright": "4.0.16",
+        "@vitest/browser-preview": "4.0.16",
+        "@vitest/browser-webdriverio": "4.0.16",
+        "@vitest/ui": "4.0.16",
+        "happy-dom": "*",
+        "jsdom": "*"
+      },
+      "peerDependenciesMeta": {
+        "@edge-runtime/vm": {
+          "optional": true
+        },
+        "@opentelemetry/api": {
+          "optional": true
+        },
+        "@types/node": {
+          "optional": true
+        },
+        "@vitest/browser-playwright": {
+          "optional": true
+        },
+        "@vitest/browser-preview": {
+          "optional": true
+        },
+        "@vitest/browser-webdriverio": {
+          "optional": true
+        },
+        "@vitest/ui": {
+          "optional": true
+        },
+        "happy-dom": {
+          "optional": true
+        },
+        "jsdom": {
+          "optional": true
+        }
+      }
+    },
    "node_modules/walker": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/walker/-/walker-1.0.8.tgz",
@ -14862,6 +15277,23 @@
        "node": ">=4"
      }
    },
+    "node_modules/why-is-node-running": {
+      "version": "2.3.0",
+      "resolved": "https://registry.npmjs.org/why-is-node-running/-/why-is-node-running-2.3.0.tgz",
+      "integrity": "sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "siginfo": "^2.0.0",
+        "stackback": "0.0.2"
+      },
+      "bin": {
+        "why-is-node-running": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
    "node_modules/widest-line": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/widest-line/-/widest-line-3.1.0.tgz",
--- a/package.json
+++ b/package.json
@ -45,10 +45,15 @@
    "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
    "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
    "release:watch": "gh run watch",
-    "test": "npm run test:schemas && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
-    "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
+    "test": "npm run test:schemas && npm run test:install && npm run test:unit && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test:coverage": "vitest run --coverage",
    "test:install": "node test/test-installation-components.js",
+    "test:integration": "vitest run test/integration",
+    "test:quick": "vitest run --changed",
    "test:schemas": "node test/test-agent-schema.js",
+    "test:ui": "vitest --ui",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
    "validate:schemas": "node tools/validate-agent-schema.js"
  },
  "lint-staged": {
@ -90,6 +95,8 @@
    "@astrojs/sitemap": "^3.6.0",
    "@astrojs/starlight": "^0.37.0",
    "@eslint/js": "^9.33.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "@vitest/ui": "^4.0.16",
    "archiver": "^7.0.1",
    "astro": "^5.16.0",
    "c8": "^10.1.3",
@ -105,6 +112,7 @@
    "prettier": "^3.7.4",
    "prettier-plugin-packagejson": "^2.5.19",
    "sharp": "^0.33.5",
+    "vitest": "^4.0.16",
    "yaml-eslint-parser": "^1.2.3",
    "yaml-lint": "^1.7.0"
  },
--- a/src/bmm/testarch/knowledge/adr-quality-readiness-checklist.md
+++ b/src/bmm/testarch/knowledge/adr-quality-readiness-checklist.md
@ -0,0 +1,350 @@
+# 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 | Sprint 0 blocker         |
+| ⬜ Sample Requests: Examples | ⬜      | Pending schemas          | Finalize ADR Tools       |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+- [ ] Backend: Implement Athena mock endpoints (Sprint 0)
+- [ ] Backend: Implement `/api/test-data` (Sprint 0)
+- [ ] PM: Finalize sample requests (Sprint 1)
+
+{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)
+
--- a/src/bmm/testarch/tea-index.csv
+++ b/src/bmm/testarch/tea-index.csv
@ -32,3 +32,4 @@ burn-in,Burn-in Runner,"Smart test selection, git diff for CI optimization","ci,
 network-error-monitor,Network Error Monitor,"HTTP 4xx/5xx detection for UI tests","monitoring,playwright-utils,ui",knowledge/network-error-monitor.md
 fixtures-composition,Fixtures Composition,"mergeTests composition patterns for combining utilities","fixtures,playwright-utils",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",knowledge/api-testing-patterns.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",knowledge/adr-quality-readiness-checklist.md
--- a/src/bmm/workflows/testarch/nfr-assess/instructions.md
+++ b/src/bmm/workflows/testarch/nfr-assess/instructions.md
@ -51,7 +51,7 @@ This workflow performs a comprehensive assessment of non-functional requirements
 **Actions:**

 1. Load relevant knowledge fragments from `{project-root}/_bmad/bmm/testarch/tea-index.csv`:
-   - `nfr-criteria.md` - Non-functional requirements criteria and thresholds (security, performance, reliability, maintainability with code examples, 658 lines, 4 examples)
+   - `adr-quality-readiness-checklist.md` - 8-category 29-criteria NFR framework (testability, test data, scalability, DR, security, monitorability, QoS/QoE, deployability, ~450 lines)
   - `ci-burn-in.md` - CI/CD burn-in patterns for reliability validation (10-iteration detection, sharding, selective execution, 678 lines, 4 examples)
   - `test-quality.md` - Test quality expectations for maintainability (deterministic, isolated, explicit assertions, length/time limits, 658 lines, 5 examples)
   - `playwright-config.md` - Performance configuration patterns: parallelization, timeout standards, artifact output (722 lines, 5 examples)
@ -75,13 +75,17 @@ This workflow performs a comprehensive assessment of non-functional requirements

 **Actions:**

-1. Determine which NFR categories to assess (default: performance, security, reliability, maintainability):
-   - **Performance**: Response time, throughput, resource usage
-   - **Security**: Authentication, authorization, data protection, vulnerability scanning
-   - **Reliability**: Error handling, recovery, availability, fault tolerance
-   - **Maintainability**: Code quality, test coverage, documentation, technical debt
+1. Determine which NFR categories to assess using ADR Quality Readiness Checklist (8 standard categories):
+   - **1. Testability & Automation**: Isolation, headless interaction, state control, sample requests (4 criteria)
+   - **2. Test Data Strategy**: Segregation, generation, teardown (3 criteria)
+   - **3. Scalability & Availability**: Statelessness, bottlenecks, SLA definitions, circuit breakers (4 criteria)
+   - **4. Disaster Recovery**: RTO/RPO, failover, backups (3 criteria)
+   - **5. Security**: AuthN/AuthZ, encryption, secrets, input validation (4 criteria)
+   - **6. Monitorability, Debuggability & Manageability**: Tracing, logs, metrics, config (4 criteria)
+   - **7. QoS & QoE**: Latency, throttling, perceived performance, degradation (4 criteria)
+   - **8. Deployability**: Zero downtime, backward compatibility, rollback (3 criteria)

-2. Add custom NFR categories if specified (e.g., accessibility, internationalization, compliance)
+2. Add custom NFR categories if specified (e.g., accessibility, internationalization, compliance) beyond the 8 standard categories

 3. Gather thresholds for each NFR:
   - From tech-spec.md (primary source)
--- a/src/bmm/workflows/testarch/nfr-assess/nfr-report-template.md
+++ b/src/bmm/workflows/testarch/nfr-assess/nfr-report-template.md
@ -355,13 +355,24 @@ Note: This assessment summarizes existing evidence; it does not run tests or CI

 ## Findings Summary

-| Category        | PASS             | CONCERNS             | FAIL             | Overall Status                      |
-| --------------- | ---------------- | -------------------- | ---------------- | ----------------------------------- |
-| Performance     | {P_PASS_COUNT}   | {P_CONCERNS_COUNT}   | {P_FAIL_COUNT}   | {P_STATUS} {P_ICON}                 |
-| Security        | {S_PASS_COUNT}   | {S_CONCERNS_COUNT}   | {S_FAIL_COUNT}   | {S_STATUS} {S_ICON}                 |
-| Reliability     | {R_PASS_COUNT}   | {R_CONCERNS_COUNT}   | {R_FAIL_COUNT}   | {R_STATUS} {R_ICON}                 |
-| Maintainability | {M_PASS_COUNT}   | {M_CONCERNS_COUNT}   | {M_FAIL_COUNT}   | {M_STATUS} {M_ICON}                 |
-| **Total**       | **{TOTAL_PASS}** | **{TOTAL_CONCERNS}** | **{TOTAL_FAIL}** | **{OVERALL_STATUS} {OVERALL_ICON}** |
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+| Category | Criteria Met | PASS | CONCERNS | FAIL | Overall Status |
+|----------|--------------|------|----------|------|----------------|
+| 1. Testability & Automation | {T_MET}/4 | {T_PASS} | {T_CONCERNS} | {T_FAIL} | {T_STATUS} {T_ICON} |
+| 2. Test Data Strategy | {TD_MET}/3 | {TD_PASS} | {TD_CONCERNS} | {TD_FAIL} | {TD_STATUS} {TD_ICON} |
+| 3. Scalability & Availability | {SA_MET}/4 | {SA_PASS} | {SA_CONCERNS} | {SA_FAIL} | {SA_STATUS} {SA_ICON} |
+| 4. Disaster Recovery | {DR_MET}/3 | {DR_PASS} | {DR_CONCERNS} | {DR_FAIL} | {DR_STATUS} {DR_ICON} |
+| 5. Security | {SEC_MET}/4 | {SEC_PASS} | {SEC_CONCERNS} | {SEC_FAIL} | {SEC_STATUS} {SEC_ICON} |
+| 6. Monitorability, Debuggability & Manageability | {MON_MET}/4 | {MON_PASS} | {MON_CONCERNS} | {MON_FAIL} | {MON_STATUS} {MON_ICON} |
+| 7. QoS & QoE | {QOS_MET}/4 | {QOS_PASS} | {QOS_CONCERNS} | {QOS_FAIL} | {QOS_STATUS} {QOS_ICON} |
+| 8. Deployability | {DEP_MET}/3 | {DEP_PASS} | {DEP_CONCERNS} | {DEP_FAIL} | {DEP_STATUS} {DEP_ICON} |
+| **Total** | **{TOTAL_MET}/29** | **{TOTAL_PASS}** | **{TOTAL_CONCERNS}** | **{TOTAL_FAIL}** | **{OVERALL_STATUS} {OVERALL_ICON}** |
+
+**Criteria Met Scoring:**
+- ≥26/29 (90%+) = Strong foundation
+- 20-25/29 (69-86%) = Room for improvement
+- <20/29 (<69%) = Significant gaps

 ---

@ -372,11 +383,16 @@ nfr_assessment:
  date: '{DATE}'
  story_id: '{STORY_ID}'
  feature_name: '{FEATURE_NAME}'
+  adr_checklist_score: '{TOTAL_MET}/29'  # ADR Quality Readiness Checklist
  categories:
-    performance: '{PERFORMANCE_STATUS}'
-    security: '{SECURITY_STATUS}'
-    reliability: '{RELIABILITY_STATUS}'
-    maintainability: '{MAINTAINABILITY_STATUS}'
+    testability_automation: '{T_STATUS}'
+    test_data_strategy: '{TD_STATUS}'
+    scalability_availability: '{SA_STATUS}'
+    disaster_recovery: '{DR_STATUS}'
+    security: '{SEC_STATUS}'
+    monitorability: '{MON_STATUS}'
+    qos_qoe: '{QOS_STATUS}'
+    deployability: '{DEP_STATUS}'
  overall_status: '{OVERALL_STATUS}'
  critical_issues: { CRITICAL_COUNT }
  high_priority_issues: { HIGH_COUNT }
--- a/src/bmm/workflows/testarch/test-design/checklist.md
+++ b/src/bmm/workflows/testarch/test-design/checklist.md
@ -1,10 +1,17 @@
 # Test Design and Risk Assessment - Validation Checklist

-## Prerequisites
+## Prerequisites (Mode-Dependent)

+**System-Level Mode (Phase 3):**
+- [ ] PRD exists with functional and non-functional requirements
+- [ ] ADR (Architecture Decision Record) exists
+- [ ] Architecture document available (architecture.md or tech-spec)
+- [ ] Requirements are testable and unambiguous
+
+**Epic-Level Mode (Phase 4):**
 - [ ] Story markdown with clear acceptance criteria exists
 - [ ] PRD or epic documentation available
- [ ] Architecture documents available (optional)
+- [ ] Architecture documents available (test-design-architecture.md + test-design-qa.md from Phase 3, if exists)
 - [ ] Requirements are testable and unambiguous

 ## Process Steps
@ -157,6 +164,80 @@
 - [ ] Risk assessment informs `gate` workflow criteria
 - [ ] Integrates with `ci` workflow execution order

+## System-Level Mode: Two-Document Validation
+
+**When in system-level mode (PRD + ADR input), validate BOTH documents:**
+
+### test-design-architecture.md
+
+- [ ] **Purpose statement** at top (serves as contract with Architecture team)
+- [ ] **Executive Summary** with scope, business context, architecture decisions, risk summary
+- [ ] **Quick Guide** section with three tiers:
+  - [ ] 🚨 BLOCKERS - Team Must Decide (Sprint 0 critical path items)
+  - [ ] ⚠️ HIGH PRIORITY - Team Should Validate (recommendations for approval)
+  - [ ] 📋 INFO ONLY - Solutions Provided (no decisions needed)
+- [ ] **Risk Assessment** section
+  - [ ] Total risks identified count
+  - [ ] High-priority risks table (score ≥6) with all columns: Risk ID, Category, Description, Probability, Impact, Score, Mitigation, Owner, Timeline
+  - [ ] Medium and low-priority risks tables
+  - [ ] Risk category legend included
+- [ ] **Testability Concerns** section (if system has architectural constraints)
+  - [ ] Blockers to fast feedback table
+  - [ ] Explanation of why standard CI/CD may not apply (if applicable)
+  - [ ] Tiered testing strategy table (if forced by architecture)
+  - [ ] Architectural improvements needed (or acknowledgment system supports testing well)
+- [ ] **Risk Mitigation Plans** for all high-priority risks (≥6)
+  - [ ] Each plan has: Strategy (numbered steps), Owner, Timeline, Status, Verification
+- [ ] **Assumptions and Dependencies** section
+  - [ ] Assumptions list (numbered)
+  - [ ] Dependencies list with required dates
+  - [ ] Risks to plan with impact and contingency
+- [ ] **NO test implementation code** (long examples belong in QA doc)
+- [ ] **NO test scenario checklists** (belong in QA doc)
+- [ ] **Cross-references to QA doc** where appropriate
+
+### test-design-qa.md
+
+- [ ] **Purpose statement** at top (execution recipe for QA team)
+- [ ] **Quick Reference for QA** section
+  - [ ] Before You Start checklist
+  - [ ] Test Execution Order
+  - [ ] Need Help? guidance
+- [ ] **System Architecture Summary** (brief overview of services and data flow)
+- [ ] **Test Environment Requirements** in early section (section 1-3, NOT buried at end)
+  - [ ] Table with Local/Dev/Staging environments
+  - [ ] Key principles listed (shared DB, randomization, parallel-safe, self-cleaning, shift-left)
+  - [ ] Code example provided
+- [ ] **Testability Assessment** with prerequisites checklist
+  - [ ] References Architecture doc blockers (not duplication)
+- [ ] **Test Levels Strategy** with unit/integration/E2E split
+  - [ ] System type identified
+  - [ ] Recommended split percentages with rationale
+  - [ ] Test count summary (P0/P1/P2/P3 totals)
+- [ ] **Test Coverage Plan** with P0/P1/P2/P3 sections
+  - [ ] Each priority has: Execution details, Purpose, Criteria, Test Count
+  - [ ] Detailed test scenarios WITH CHECKBOXES
+  - [ ] Coverage table with columns: Requirement | Test Level | Risk Link | Test Count | Owner | Notes
+- [ ] **Sprint 0 Setup Requirements**
+  - [ ] Architecture/Backend blockers listed with cross-references to Architecture doc
+  - [ ] QA Test Infrastructure section (factories, fixtures)
+  - [ ] Test Environments section (Local, CI/CD, Staging, Production)
+  - [ ] Sprint 0 NFR Gates checklist
+  - [ ] Sprint 1 Items clearly separated
+- [ ] **NFR Readiness Summary** (reference to Architecture doc, not duplication)
+  - [ ] Table with NFR categories, status, evidence, blocker, next action
+- [ ] **Cross-references to Architecture doc** (not duplication)
+- [ ] **NO architectural theory** (just reference Architecture doc)
+
+### Cross-Document Consistency
+
+- [ ] Both documents reference same risks by ID (R-001, R-002, etc.)
+- [ ] Both documents use consistent priority levels (P0, P1, P2, P3)
+- [ ] Both documents reference same Sprint 0 blockers
+- [ ] No duplicate content (cross-reference instead)
+- [ ] Dates and authors match across documents
+- [ ] ADR and PRD references consistent
+
 ## Completion Criteria

 **All must be true:**
@ -166,7 +247,9 @@
 - [ ] All output validations passed
 - [ ] All quality checks passed
 - [ ] All integration points verified
- [ ] Output file complete and well-formatted
+- [ ] Output file(s) complete and well-formatted
+- [ ] **System-level mode:** Both documents validated (if applicable)
+- [ ] **Epic-level mode:** Single document validated (if applicable)
 - [ ] Team review scheduled (if required)

 ## Post-Workflow Actions
--- a/src/bmm/workflows/testarch/test-design/instructions.md
+++ b/src/bmm/workflows/testarch/test-design/instructions.md
@ -22,28 +22,64 @@ The workflow auto-detects which mode to use based on project phase.

 **Critical:** Determine mode before proceeding.

-### Mode Detection
+### Mode Detection (Flexible for Standalone Use)

-1. **Check for sprint-status.yaml**
-   - If `{implementation_artifacts}/sprint-status.yaml` exists → **Epic-Level Mode** (Phase 4)
-   - If NOT exists → Check workflow status
+TEA test-design workflow supports TWO modes, detected automatically:

-2. **Mode-Specific Requirements**
+1. **Check User Intent Explicitly (Priority 1)**

-   **System-Level Mode (Phase 3 - Testability Review):**
-   - ✅ Architecture document exists (architecture.md or tech-spec)
-   - ✅ PRD exists with functional and non-functional requirements
-   - ✅ Epics documented (epics.md)
-   - ⚠️ Output: `{output_folder}/test-design-system.md`
+   **Deterministic Rules:**
+   - User provided **PRD+ADR only** (no Epic+Stories) → **System-Level Mode**
+   - User provided **Epic+Stories only** (no PRD+ADR) → **Epic-Level Mode**
+   - User provided **BOTH PRD+ADR AND Epic+Stories** → **Prefer System-Level Mode** (architecture review comes first in Phase 3, then epic planning in Phase 4). If mode preference is unclear, ask user: "Should I create (A) System-level test design (PRD + ADR → Architecture doc + QA doc) or (B) Epic-level test design (Epic → Single test plan)?"
+   - If user intent is clear from context, use that mode regardless of file structure

-   **Epic-Level Mode (Phase 4 - Per-Epic Planning):**
-   - ✅ Story markdown with acceptance criteria available
-   - ✅ PRD or epic documentation exists for context
-   - ✅ Architecture documents available (optional but recommended)
-   - ✅ Requirements are clear and testable
-   - ⚠️ Output: `{output_folder}/test-design-epic-{epic_num}.md`
+2. **Fallback to File-Based Detection (Priority 2 - BMad-Integrated)**
+   - Check for `{implementation_artifacts}/sprint-status.yaml`
+   - If exists → **Epic-Level Mode** (Phase 4, single document output)
+   - If NOT exists → **System-Level Mode** (Phase 3, TWO document outputs)

-**Halt Condition:** If mode cannot be determined or required files missing, HALT and notify user with missing prerequisites.
+3. **If Ambiguous, ASK USER (Priority 3)**
+   - "I see you have [PRD/ADR/Epic/Stories]. Should I create:
+     - (A) System-level test design (PRD + ADR → Architecture doc + QA doc)?
+     - (B) Epic-level test design (Epic → Single test plan)?"
+
+**Mode Descriptions:**
+
+**System-Level Mode (PRD + ADR Input)**
+- **When to use:** Early in project (Phase 3 Solutioning), architecture being designed
+- **Input:** PRD, ADR, architecture.md (optional)
+- **Output:** TWO documents
+  - `test-design-architecture.md` (for Architecture/Dev teams)
+  - `test-design-qa.md` (for QA team)
+- **Focus:** Testability assessment, ASRs, NFR requirements, Sprint 0 setup
+
+**Epic-Level Mode (Epic + Stories Input)**
+- **When to use:** During implementation (Phase 4), per-epic planning
+- **Input:** Epic, Stories, tech-specs (optional)
+- **Output:** ONE document
+  - `test-design-epic-{N}.md` (combined risk assessment + test plan)
+- **Focus:** Risk assessment, coverage plan, execution order, quality gates
+
+**Key Insight: TEA Works Standalone OR Integrated**
+
+**Standalone (No BMad artifacts):**
+- User provides PRD + ADR → System-Level Mode
+- User provides Epic description → Epic-Level Mode
+- TEA doesn't mandate full BMad workflow
+
+**BMad-Integrated (Full workflow):**
+- BMad creates `sprint-status.yaml` → Automatic Epic-Level detection
+- BMad creates PRD, ADR, architecture.md → Automatic System-Level detection
+- TEA leverages BMad artifacts for richer context
+
+**Message to User:**
+> You don't need to follow full BMad methodology to use TEA test-design.
+> Just provide PRD + ADR for system-level, or Epic for epic-level.
+> TEA will auto-detect and produce appropriate documents.
+
+**Halt Condition:** If mode cannot be determined AND user intent unclear AND required files missing, HALT and notify user:
+- "Please provide either: (A) PRD + ADR for system-level test design, OR (B) Epic + Stories for epic-level test design"

 ---

@ -69,8 +105,8 @@ The workflow auto-detects which mode to use based on project phase.

 3. **Load Knowledge Base Fragments (System-Level)**

-   **Critical:** Consult `{project-root}/_bmad/bmm/testarch/tea-index.csv` to load:
-   - `nfr-criteria.md` - NFR validation approach (security, performance, reliability, maintainability)
+   **Critical:** Consult `src/bmm/testarch/tea-index.csv` to load:
+   - `adr-quality-readiness-checklist.md` - 8-category 29-criteria NFR framework (testability, security, scalability, DR, QoS, deployability, etc.)
   - `test-levels-framework.md` - Test levels strategy guidance
   - `risk-governance.md` - Testability risk identification
   - `test-quality.md` - Quality standards and Definition of Done
@ -91,7 +127,7 @@ The workflow auto-detects which mode to use based on project phase.
 2. **Load Architecture Context**
   - Read architecture.md for system design
   - Read tech-spec for implementation details
-   - Read test-design-system.md (if exists from Phase 3)
+   - Read test-design-architecture.md and test-design-qa.md (if exist from Phase 3 system-level test design)
   - Identify technical constraints and dependencies
   - Note integration points and external systems

@ -103,7 +139,7 @@ The workflow auto-detects which mode to use based on project phase.

 4. **Load Knowledge Base Fragments (Epic-Level)**

-   **Critical:** Consult `{project-root}/_bmad/bmm/testarch/tea-index.csv` to load:
+   **Critical:** Consult `src/bmm/testarch/tea-index.csv` to load:
   - `risk-governance.md` - Risk classification framework (6 categories: TECH, SEC, PERF, DATA, BUS, OPS), automated scoring, gate decision engine, owner tracking (625 lines, 4 examples)
   - `probability-impact.md` - Risk scoring methodology (probability × impact matrix, automated classification, dynamic re-assessment, gate integration, 604 lines, 4 examples)
   - `test-levels-framework.md` - Test level selection guidance (E2E vs API vs Component vs Unit with decision matrix, characteristics, when to use each, 467 lines, 4 examples)
@ -173,50 +209,128 @@ The workflow auto-detects which mode to use based on project phase.

   **Critical:** If testability concerns are blockers (e.g., "Architecture makes performance testing impossible"), document as CONCERNS or FAIL recommendation for gate check.

-6. **Output System-Level Test Design**
+6. **Output System-Level Test Design (TWO Documents)**

-   Write to `{output_folder}/test-design-system.md` containing:
+   **IMPORTANT:** System-level mode produces TWO documents instead of one:
+
+   **Document 1: test-design-architecture.md** (for Architecture/Dev teams)
+   - Purpose: Architectural concerns, testability gaps, NFR requirements
+   - Audience: Architects, Backend Devs, Frontend Devs, DevOps, Security Engineers
+   - Focus: What architecture must deliver for testability
+   - Template: `test-design-architecture-template.md`
+
+   **Document 2: test-design-qa.md** (for QA team)
+   - Purpose: Test execution recipe, coverage plan, Sprint 0 setup
+   - Audience: QA Engineers, Test Automation Engineers, QA Leads
+   - Focus: How QA will execute tests
+   - Template: `test-design-qa-template.md`
+
+   **Standard Structures (REQUIRED):**
+
+   **test-design-architecture.md sections (in this order):**
+   1. Executive Summary (scope, business context, architecture, risk summary)
+   2. Quick Guide (🚨 BLOCKERS / ⚠️ HIGH PRIORITY / 📋 INFO ONLY)
+   3. Risk Assessment (high/medium/low-priority risks with scoring)
+   4. Testability Concerns and Architectural Gaps (if system has constraints)
+   5. Risk Mitigation Plans (detailed for high-priority risks ≥6)
+   6. Assumptions and Dependencies
+
+   **test-design-qa.md sections (in this order):**
+   1. Quick Reference for QA (Before You Start, Execution Order, Need Help)
+   2. System Architecture Summary (brief overview)
+   3. Test Environment Requirements (MOVE UP - section 3, NOT buried at end)
+   4. Testability Assessment (lightweight prerequisites checklist)
+   5. Test Levels Strategy (unit/integration/E2E split with rationale)
+   6. Test Coverage Plan (P0/P1/P2/P3 with detailed scenarios + checkboxes)
+   7. Sprint 0 Setup Requirements (blockers, infrastructure, environments)
+   8. NFR Readiness Summary (reference to Architecture doc)
+
+   **Content Guidelines:**
+
+   **Architecture doc (DO):**
+   - ✅ Risk scoring visible (Probability × Impact = Score)
+   - ✅ Clear ownership (each blocker/ASR has owner + timeline)
+   - ✅ Testability requirements (what architecture must support)
+   - ✅ Mitigation plans (for each high-risk item ≥6)
+   - ✅ Short code examples (5-10 lines max showing what to support)
+
+   **Architecture doc (DON'T):**
+   - ❌ NO long test code examples (belongs in QA doc)
+   - ❌ NO test scenario checklists (belongs in QA doc)
+   - ❌ NO implementation details (how QA will test)
+
+   **QA doc (DO):**
+   - ✅ Test scenario recipes (clear P0/P1/P2/P3 with checkboxes)
+   - ✅ Environment setup (Sprint 0 checklist with blockers)
+   - ✅ Tool setup (factories, fixtures, frameworks)
+   - ✅ Cross-references to Architecture doc (not duplication)
+
+   **QA doc (DON'T):**
+   - ❌ NO architectural theory (just reference Architecture doc)
+   - ❌ NO ASR explanations (link to Architecture doc instead)
+   - ❌ NO duplicate risk assessments (reference Architecture doc)
+
+   **Anti-Patterns to Avoid (Cross-Document Redundancy):**
+
+   ❌ **DON'T duplicate OAuth requirements:**
+   - Architecture doc: Explain OAuth 2.1 flow in detail
+   - QA doc: Re-explain why OAuth 2.1 is required
+
+   ✅ **DO cross-reference instead:**
+   - Architecture doc: "ASR-1: OAuth 2.1 required (see QA doc for 12 test scenarios)"
+   - QA doc: "OAuth tests: 12 P0 scenarios (see Architecture doc R-001 for risk details)"
+
+   **Markdown Cross-Reference Syntax Examples:**

   ```markdown
-   # System-Level Test Design
+   # In test-design-architecture.md
+
+   ### 🚨 R-001: Multi-Tenant Isolation (Score: 9)
+
+   **Test Coverage:** 8 P0 tests (see [QA doc - Multi-Tenant Isolation](test-design-qa.md#multi-tenant-isolation-8-tests-security-critical) for detailed scenarios)
+
+   ---
+
+   # In test-design-qa.md

   ## Testability Assessment

-   - Controllability: [PASS/CONCERNS/FAIL with details]
-   - Observability: [PASS/CONCERNS/FAIL with details]
-   - Reliability: [PASS/CONCERNS/FAIL with details]
+   **Prerequisites from Architecture Doc:**
+   - [ ] R-001: Multi-tenant isolation validated (see [Architecture doc R-001](test-design-architecture.md#r-001-multi-tenant-isolation-score-9) for mitigation plan)
+   - [ ] R-002: Test customer provisioned (see [Architecture doc 🚨 BLOCKERS](test-design-architecture.md#blockers---team-must-decide-cant-proceed-without))

-   ## Architecturally Significant Requirements (ASRs)
+   ## Sprint 0 Setup Requirements

-   [Risk-scored quality requirements]
-
-   ## Test Levels Strategy
-
-   - Unit: [X%] - [Rationale]
-   - Integration: [Y%] - [Rationale]
-   - E2E: [Z%] - [Rationale]
-
-   ## NFR Testing Approach
-
-   - Security: [Approach with tools]
-   - Performance: [Approach with tools]
-   - Reliability: [Approach with tools]
-   - Maintainability: [Approach with tools]
-
-   ## Test Environment Requirements
-
-   [Infrastructure needs based on deployment architecture]
-
-   ## Testability Concerns (if any)
-
-   [Blockers or concerns that should inform solutioning gate check]
-
-   ## Recommendations for Sprint 0
-
-   [Specific actions for *framework and *ci workflows]
+   **Source:** See [Architecture doc "Quick Guide"](test-design-architecture.md#quick-guide) for detailed mitigation plans
   ```

-**After System-Level Mode:** Skip to Step 4 (Generate Deliverables) - Steps 2-3 are epic-level only.
+   **Key Points:**
+   - Use relative links: `[Link Text](test-design-qa.md#section-anchor)`
+   - Anchor format: lowercase, hyphens for spaces, remove emojis/special chars
+   - Example anchor: `### 🚨 R-001: Title` → `#r-001-title`
+
+   ❌ **DON'T put long code examples in Architecture doc:**
+   - Example: 50+ lines of test implementation
+
+   ✅ **DO keep examples SHORT in Architecture doc:**
+   - Example: 5-10 lines max showing what architecture must support
+   - Full implementation goes in QA doc
+
+   ❌ **DON'T repeat same note 10+ times:**
+   - Example: "Pessimistic timing until R-005 fixed" on every P0/P1/P2 section
+
+   ✅ **DO consolidate repeated notes:**
+   - Single timing note at top
+   - Reference briefly throughout: "(pessimistic)"
+
+   **Write Both Documents:**
+   - Use `test-design-architecture-template.md` for Architecture doc
+   - Use `test-design-qa-template.md` for QA doc
+   - Follow standard structures defined above
+   - Cross-reference between docs (no duplication)
+   - Validate against checklist.md (System-Level Mode section)
+
+**After System-Level Mode:** Workflow COMPLETE. System-level outputs (test-design-architecture.md + test-design-qa.md) are written in this step. Steps 2-4 are epic-level only - do NOT execute them in system-level mode.

 ---

--- a/src/bmm/workflows/testarch/test-design/test-design-architecture-template.md
+++ b/src/bmm/workflows/testarch/test-design/test-design-architecture-template.md
@ -0,0 +1,216 @@
+# Test Design for Architecture: {Feature Name}
+
+**Purpose:** Architectural concerns, testability gaps, and NFR requirements for review by Architecture/Dev teams. Serves as a contract between QA and Engineering on what must be addressed before test development begins.
+
+**Date:** {date}
+**Author:** {author}
+**Status:** Architecture Review Pending
+**Project:** {project_name}
+**PRD Reference:** {prd_link}
+**ADR Reference:** {adr_link}
+
+---
+
+## Executive Summary
+
+**Scope:** {Brief description of feature scope}
+
+**Business Context** (from PRD):
+- **Revenue/Impact:** {Business metrics if applicable}
+- **Problem:** {Problem being solved}
+- **GA Launch:** {Target date or timeline}
+
+**Architecture** (from ADR {adr_number}):
+- **Key Decision 1:** {e.g., OAuth 2.1 authentication}
+- **Key Decision 2:** {e.g., Centralized MCP Server pattern}
+- **Key Decision 3:** {e.g., Stack: TypeScript, SDK v1.x}
+
+**Expected Scale** (from ADR):
+- {RPS, volume, users, etc.}
+
+**Risk Summary:**
+- **Total risks**: {N}
+- **High-priority (≥6)**: {N} risks requiring immediate mitigation
+- **Test effort**: ~{N} tests (~{X} weeks for 1 QA, ~{Y} weeks for 2 QAs)
+
+---
+
+## Quick Guide
+
+### 🚨 BLOCKERS - Team Must Decide (Can't Proceed Without)
+
+**Sprint 0 Critical Path** - These MUST be completed before QA can write integration tests:
+
+1. **{Blocker ID}: {Blocker Title}** - {What architecture must provide} (recommended owner: {Team/Role})
+2. **{Blocker ID}: {Blocker Title}** - {What architecture must provide} (recommended owner: {Team/Role})
+3. **{Blocker ID}: {Blocker Title}** - {What architecture must provide} (recommended owner: {Team/Role})
+
+**What we need from team:** Complete these {N} items in Sprint 0 or test development is blocked.
+
+---
+
+### ⚠️ HIGH PRIORITY - Team Should Validate (We Provide Recommendation, You Approve)
+
+1. **{Risk ID}: {Title}** - {Recommendation + who should approve} (Sprint {N})
+2. **{Risk ID}: {Title}** - {Recommendation + who should approve} (Sprint {N})
+3. **{Risk ID}: {Title}** - {Recommendation + who should approve} (Sprint {N})
+
+**What we need from team:** Review recommendations and approve (or suggest changes).
+
+---
+
+### 📋 INFO ONLY - Solutions Provided (Review, No Decisions Needed)
+
+1. **Test strategy**: {Test level split} ({Rationale})
+2. **Tooling**: {Test frameworks and utilities}
+3. **Tiered CI/CD**: {Execution tiers with timing}
+4. **Coverage**: ~{N} test scenarios prioritized P0-P3 with risk-based classification
+5. **Quality gates**: {Pass criteria}
+
+**What we need from team:** Just review and acknowledge (we already have the solution).
+
+---
+
+## For Architects and Devs - Open Topics 👷
+
+### Risk Assessment
+
+**Total risks identified**: {N} ({X} high-priority score ≥6, {Y} medium, {Z} low)
+
+#### High-Priority Risks (Score ≥6) - IMMEDIATE ATTENTION
+
+| Risk ID | Category | Description | Probability | Impact | Score | Mitigation | Owner | Timeline |
+|---------|----------|-------------|-------------|--------|-------|------------|-------|----------|
+| **{R-ID}** | **{CAT}** | {Description} | {1-3} | {1-3} | **{Score}** | {Mitigation strategy} | {Owner} | {Date} |
+
+#### Medium-Priority Risks (Score 3-5)
+
+| Risk ID | Category | Description | Probability | Impact | Score | Mitigation | Owner |
+|---------|----------|-------------|-------------|--------|-------|------------|-------|
+| {R-ID} | {CAT} | {Description} | {1-3} | {1-3} | {Score} | {Mitigation} | {Owner} |
+
+#### Low-Priority Risks (Score 1-2)
+
+| Risk ID | Category | Description | Probability | Impact | Score | Action |
+|---------|----------|-------------|-------------|--------|-------|--------|
+| {R-ID} | {CAT} | {Description} | {1-3} | {1-3} | {Score} | Monitor |
+
+#### Risk Category Legend
+
+- **TECH**: Technical/Architecture (flaws, integration, scalability)
+- **SEC**: Security (access controls, auth, data exposure)
+- **PERF**: Performance (SLA violations, degradation, resource limits)
+- **DATA**: Data Integrity (loss, corruption, inconsistency)
+- **BUS**: Business Impact (UX harm, logic errors, revenue)
+- **OPS**: Operations (deployment, config, monitoring)
+
+---
+
+### Testability Concerns and Architectural Gaps
+
+**IMPORTANT**: {If system has constraints, explain them. If standard CI/CD achievable, state that.}
+
+#### Blockers to Fast Feedback
+
+| Blocker | Impact | Current Mitigation | Ideal Solution |
+|---------|--------|-------------------|----------------|
+| **{Blocker name}** | {Impact description} | {How we're working around it} | {What architecture should provide} |
+
+#### Why This Matters
+
+**Standard CI/CD expectations:**
+- Full test suite on every commit (~5-15 min feedback)
+- Parallel test execution (isolated test data per worker)
+- Ephemeral test environments (spin up → test → tear down)
+- Fast feedback loop (devs stay in flow state)
+
+**Current reality for {Feature}:**
+- {Actual situation - what's different from standard}
+
+#### Tiered Testing Strategy
+
+{If forced by architecture, explain. If standard approach works, state that.}
+
+| Tier | When | Duration | Coverage | Why Not Full Suite? |
+|------|------|----------|----------|---------------------|
+| **Smoke** | Every commit | <5 min | {N} tests | Fast feedback, catch build-breaking changes |
+| **P0** | Every commit | ~{X} min | ~{N} tests | Critical paths, security-critical flows |
+| **P1** | PR to main | ~{X} min | ~{N} tests | Important features, algorithm accuracy |
+| **P2/P3** | Nightly | ~{X} min | ~{N} tests | Edge cases, performance, NFR |
+
+**Note**: {Any timing assumptions or constraints}
+
+#### Architectural Improvements Needed
+
+{If system has technical debt affecting testing, list improvements. If architecture supports testing well, acknowledge that.}
+
+1. **{Improvement name}**
+   - {What to change}
+   - **Impact**: {How it improves testing}
+
+#### Acceptance of Trade-offs
+
+For {Feature} Phase 1, the team accepts:
+- **{Trade-off 1}** ({Reasoning})
+- **{Trade-off 2}** ({Reasoning})
+- ⚠️ **{Known limitation}** ({Why acceptable for now})
+
+This is {**technical debt** OR **acceptable for Phase 1**} that should be {revisited post-GA OR maintained as-is}.
+
+---
+
+### Risk Mitigation Plans (High-Priority Risks ≥6)
+
+**Purpose**: Detailed mitigation strategies for all {N} high-priority risks (score ≥6). These risks MUST be addressed before {GA launch date or milestone}.
+
+#### {R-ID}: {Risk Description} (Score: {Score}) - {CRITICALITY LEVEL}
+
+**Mitigation Strategy:**
+1. {Step 1}
+2. {Step 2}
+3. {Step 3}
+
+**Owner:** {Owner}
+**Timeline:** {Sprint or date}
+**Status:** Planned / In Progress / Complete
+**Verification:** {How to verify mitigation is effective}
+
+---
+
+{Repeat for all high-priority risks}
+
+---
+
+### Assumptions and Dependencies
+
+#### Assumptions
+
+1. {Assumption about architecture or requirements}
+2. {Assumption about team or timeline}
+3. {Assumption about scope or constraints}
+
+#### Dependencies
+
+1. {Dependency} - Required by {date/sprint}
+2. {Dependency} - Required by {date/sprint}
+
+#### Risks to Plan
+
+- **Risk**: {Risk to the test plan itself}
+  - **Impact**: {How it affects testing}
+  - **Contingency**: {Backup plan}
+
+---
+
+**End of Architecture Document**
+
+**Next Steps for Architecture Team:**
+1. Review Quick Guide (🚨/⚠️/📋) and prioritize blockers
+2. Assign owners and timelines for high-priority risks (≥6)
+3. Validate assumptions and dependencies
+4. Provide feedback to QA on testability gaps
+
+**Next Steps for QA Team:**
+1. Wait for Sprint 0 blockers to be resolved
+2. Refer to companion QA doc (test-design-qa.md) for test scenarios
+3. Begin test infrastructure setup (factories, fixtures, environments)
--- a/src/bmm/workflows/testarch/test-design/test-design-qa-template.md
+++ b/src/bmm/workflows/testarch/test-design/test-design-qa-template.md
@ -0,0 +1,314 @@
+# Test Design for QA: {Feature Name}
+
+**Purpose:** Test execution recipe for QA team. Defines test scenarios, coverage plan, tooling, and Sprint 0 setup requirements. Use this as your implementation guide after architectural blockers are resolved.
+
+**Date:** {date}
+**Author:** {author}
+**Status:** Draft / Ready for Implementation
+**Project:** {project_name}
+**PRD Reference:** {prd_link}
+**ADR Reference:** {adr_link}
+
+---
+
+## Quick Reference for QA
+
+**Before You Start:**
+- [ ] Review Architecture doc (test-design-architecture.md) - understand blockers and risks
+- [ ] Verify Sprint 0 blockers resolved (see Sprint 0 section below)
+- [ ] Confirm test infrastructure ready (factories, fixtures, environments)
+
+**Test Execution Order:**
+1. **Smoke tests** (<5 min) - Fast feedback on critical paths
+2. **P0 tests** (~{X} min) - Critical paths, security-critical flows
+3. **P1 tests** (~{X} min) - Important features, algorithm accuracy
+4. **P2/P3 tests** (~{X} min) - Edge cases, performance, NFR
+
+**Need Help?**
+- Blockers: See Architecture doc "Quick Guide" for mitigation plans
+- Test scenarios: See "Test Coverage Plan" section below
+- Sprint 0 setup: See "Sprint 0 Setup Requirements" section
+
+---
+
+## System Architecture Summary
+
+**Data Pipeline:**
+{Brief description of system flow}
+
+**Key Services:**
+- **{Service 1}**: {Purpose and key responsibilities}
+- **{Service 2}**: {Purpose and key responsibilities}
+- **{Service 3}**: {Purpose and key responsibilities}
+
+**Data Stores:**
+- **{Database 1}**: {What it stores}
+- **{Database 2}**: {What it stores}
+
+**Expected Scale** (from ADR):
+- {Key metrics: RPS, volume, users, etc.}
+
+---
+
+## Test Environment Requirements
+
+**{Company} Standard:** Shared DB per Environment with Randomization (Shift-Left)
+
+| Environment | Database | Test Data Strategy | Purpose |
+|-------------|----------|-------------------|---------|
+| **Local** | {DB} (shared) | Randomized (faker), auto-cleanup | Local development |
+| **Dev (CI)** | {DB} (shared) | Randomized (faker), auto-cleanup | PR validation |
+| **Staging** | {DB} (shared) | Randomized (faker), auto-cleanup | Pre-production, E2E |
+
+**Key Principles:**
+- **Shared database per environment** (no ephemeral)
+- **Randomization for isolation** (faker-based unique IDs)
+- **Parallel-safe** (concurrent test runs don't conflict)
+- **Self-cleaning** (tests delete their own data)
+- **Shift-left** (test against real DBs early)
+
+**Example:**
+
+```typescript
+import { faker } from "@faker-js/faker";
+
+test("example with randomized test data @p0", async ({ apiRequest }) => {
+  const testData = {
+    id: `test-${faker.string.uuid()}`,
+    customerId: `test-customer-${faker.string.alphanumeric(8)}`,
+    // ... unique test data
+  };
+
+  // Seed, test, cleanup
+});
+```
+
+---
+
+## Testability Assessment
+
+**Prerequisites from Architecture Doc:**
+
+Verify these blockers are resolved before test development:
+- [ ] {Blocker 1} (see Architecture doc Quick Guide → 🚨 BLOCKERS)
+- [ ] {Blocker 2}
+- [ ] {Blocker 3}
+
+**If Prerequisites Not Met:** Coordinate with Architecture team (see Architecture doc for mitigation plans and owner assignments)
+
+---
+
+## Test Levels Strategy
+
+**System Type:** {API-heavy / UI-heavy / Mixed backend system}
+
+**Recommended Split:**
+- **Unit Tests: {X}%** - {What to unit test}
+- **Integration/API Tests: {X}%** - ⭐ **PRIMARY FOCUS** - {What to integration test}
+- **E2E Tests: {X}%** - {What to E2E test}
+
+**Rationale:** {Why this split makes sense for this system}
+
+**Test Count Summary:**
+- P0: ~{N} tests - Critical paths, run on every commit
+- P1: ~{N} tests - Important features, run on PR to main
+- P2: ~{N} tests - Edge cases, run nightly/weekly
+- P3: ~{N} tests - Exploratory, run on-demand
+- **Total: ~{N} tests** (~{X} weeks for 1 QA, ~{Y} weeks for 2 QAs)
+
+---
+
+## Test Coverage Plan
+
+**Repository Note:** {Where tests live - backend repo, admin panel repo, etc. - and how CI pipelines are organized}
+
+### P0 (Critical) - Run on every commit (~{X} min)
+
+**Execution:** CI/CD on every commit, parallel workers, smoke tests first (<5 min)
+
+**Purpose:** Critical path validation - catch build-breaking changes and security violations immediately
+
+**Criteria:** Blocks core functionality OR High risk (≥6) OR No workaround
+
+**Key Smoke Tests** (subset of P0, run first for fast feedback):
+- {Smoke test 1} - {Duration}
+- {Smoke test 2} - {Duration}
+- {Smoke test 3} - {Duration}
+
+| Requirement | Test Level | Risk Link | Test Count | Owner | Notes |
+|-------------|------------|-----------|------------|-------|-------|
+| {Requirement 1} | {Level} | {R-ID} | {N} | QA | {Notes} |
+| {Requirement 2} | {Level} | {R-ID} | {N} | QA | {Notes} |
+
+**Total P0:** ~{N} tests (~{X} weeks)
+
+#### P0 Test Scenarios (Detailed)
+
+**1. {Test Category} ({N} tests) - {CRITICALITY if applicable}**
+
+- [ ] {Scenario 1 with checkbox}
+- [ ] {Scenario 2}
+- [ ] {Scenario 3}
+
+**2. {Test Category 2} ({N} tests)**
+
+- [ ] {Scenario 1}
+- [ ] {Scenario 2}
+
+{Continue for all P0 categories}
+
+---
+
+### P1 (High) - Run on PR to main (~{X} min additional)
+
+**Execution:** CI/CD on pull requests to main branch, runs after P0 passes, parallel workers
+
+**Purpose:** Important feature coverage - algorithm accuracy, complex workflows, Admin Panel interactions
+
+**Criteria:** Important features OR Medium risk (3-4) OR Common workflows
+
+| Requirement | Test Level | Risk Link | Test Count | Owner | Notes |
+|-------------|------------|-----------|------------|-------|-------|
+| {Requirement 1} | {Level} | {R-ID} | {N} | QA | {Notes} |
+| {Requirement 2} | {Level} | {R-ID} | {N} | QA | {Notes} |
+
+**Total P1:** ~{N} tests (~{X} weeks)
+
+#### P1 Test Scenarios (Detailed)
+
+**1. {Test Category} ({N} tests)**
+
+- [ ] {Scenario 1}
+- [ ] {Scenario 2}
+
+{Continue for all P1 categories}
+
+---
+
+### P2 (Medium) - Run nightly/weekly (~{X} min)
+
+**Execution:** Scheduled nightly run (or weekly for P3), full infrastructure, sequential execution acceptable
+
+**Purpose:** Edge case coverage, error handling, data integrity validation - slow feedback acceptable
+
+**Criteria:** Secondary features OR Low risk (1-2) OR Edge cases
+
+| Requirement | Test Level | Risk Link | Test Count | Owner | Notes |
+|-------------|------------|-----------|------------|-------|-------|
+| {Requirement 1} | {Level} | {R-ID} | {N} | QA | {Notes} |
+| {Requirement 2} | {Level} | {R-ID} | {N} | QA | {Notes} |
+
+**Total P2:** ~{N} tests (~{X} weeks)
+
+---
+
+### P3 (Low) - Run on-demand (exploratory)
+
+**Execution:** Manual trigger or weekly scheduled run, performance testing
+
+**Purpose:** Full regression, performance benchmarks, accessibility validation - no time pressure
+
+**Criteria:** Nice-to-have OR Exploratory OR Performance benchmarks
+
+| Requirement | Test Level | Test Count | Owner | Notes |
+|-------------|------------|------------|-------|-------|
+| {Requirement 1} | {Level} | {N} | QA | {Notes} |
+| {Requirement 2} | {Level} | {N} | QA | {Notes} |
+
+**Total P3:** ~{N} tests (~{X} days)
+
+---
+
+### Coverage Matrix (Requirements → Tests)
+
+| Requirement | Test Level | Priority | Risk Link | Test Count | Owner |
+|-------------|------------|----------|-----------|------------|-------|
+| {Requirement 1} | {Level} | {P0-P3} | {R-ID} | {N} | {Owner} |
+| {Requirement 2} | {Level} | {P0-P3} | {R-ID} | {N} | {Owner} |
+
+---
+
+## Sprint 0 Setup Requirements
+
+**IMPORTANT:** These items **BLOCK test development**. Complete in Sprint 0 before QA can write tests.
+
+### Architecture/Backend Blockers (from Architecture doc)
+
+**Source:** See Architecture doc "Quick Guide" for detailed mitigation plans
+
+1. **{Blocker 1}** 🚨 **BLOCKER** - {Owner}
+   - {What needs to be provided}
+   - **Details:** Architecture doc {Risk-ID} mitigation plan
+
+2. **{Blocker 2}** 🚨 **BLOCKER** - {Owner}
+   - {What needs to be provided}
+   - **Details:** Architecture doc {Risk-ID} mitigation plan
+
+### QA Test Infrastructure
+
+1. **{Factory/Fixture Name}** - QA
+   - Faker-based generator: `{function_signature}`
+   - Auto-cleanup after tests
+
+2. **{Entity} Fixtures** - QA
+   - Seed scripts for {states/scenarios}
+   - Isolated {id_pattern} per test
+
+### Test Environments
+
+**Local:** {Setup details - Docker, LocalStack, etc.}
+
+**CI/CD:** {Setup details - shared infrastructure, parallel workers, artifacts}
+
+**Staging:** {Setup details - shared multi-tenant, nightly E2E}
+
+**Production:** {Setup details - feature flags, canary transactions}
+
+**Sprint 0 NFR Gates** (MUST complete before integration testing):
+- [ ] {Gate 1}: {Description} (Owner) 🚨
+- [ ] {Gate 2}: {Description} (Owner) 🚨
+- [ ] {Gate 3}: {Description} (Owner) 🚨
+
+### Sprint 1 Items (Not Sprint 0)
+
+- **{Item 1}** ({Owner}): {Description}
+- **{Item 2}** ({Owner}): {Description}
+
+**Sprint 1 NFR Gates** (MUST complete before GA):
+- [ ] {Gate 1}: {Description} (Owner)
+- [ ] {Gate 2}: {Description} (Owner)
+
+---
+
+## NFR Readiness Summary
+
+**Based on Architecture Doc Risk Assessment**
+
+| NFR Category | Status | Evidence Status | Blocker | Next Action |
+|--------------|--------|-----------------|---------|-------------|
+| **Testability & Automation** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **Test Data Strategy** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **Scalability & Availability** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **Disaster Recovery** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **Security** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **Monitorability, Debuggability & Manageability** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **QoS & QoE** | {Status} | {Evidence} | {Sprint} | {Action} |
+| **Deployability** | {Status} | {Evidence} | {Sprint} | {Action} |
+
+**Total:** {N} PASS, {N} CONCERNS across {N} categories
+
+---
+
+**End of QA Document**
+
+**Next Steps for QA Team:**
+1. Verify Sprint 0 blockers resolved (coordinate with Architecture team if not)
+2. Set up test infrastructure (factories, fixtures, environments)
+3. Begin test implementation following priority order (P0 → P1 → P2 → P3)
+4. Run smoke tests first for fast feedback
+5. Track progress using test scenario checklists above
+
+**Next Steps for Architecture Team:**
+1. Monitor Sprint 0 blocker resolution
+2. Provide support for QA infrastructure setup if needed
+3. Review test results and address any newly discovered testability gaps
--- a/src/bmm/workflows/testarch/test-design/workflow.yaml
+++ b/src/bmm/workflows/testarch/test-design/workflow.yaml
@ -15,6 +15,9 @@ date: system-generated
 installed_path: "{project-root}/_bmad/bmm/workflows/testarch/test-design"
 instructions: "{installed_path}/instructions.md"
 validation: "{installed_path}/checklist.md"
+# Note: Template selection is mode-based (see instructions.md Step 1.5):
+#   - System-level: test-design-architecture-template.md + test-design-qa-template.md
+#   - Epic-level: test-design-template.md (unchanged)
 template: "{installed_path}/test-design-template.md"

 # Variables and inputs
@ -26,13 +29,25 @@ variables:
 # Note: Actual output file determined dynamically based on mode detection
 # Declared outputs for new workflow format
 outputs:
-  - id: system-level
-    description: "System-level testability review (Phase 3)"
-    path: "{output_folder}/test-design-system.md"
+  # System-Level Mode (Phase 3) - TWO documents
+  - id: test-design-architecture
+    description: "System-level test architecture: Architectural concerns, testability gaps, NFR requirements for Architecture/Dev teams"
+    path: "{output_folder}/test-design-architecture.md"
+    mode: system-level
+    audience: architecture
+
+  - id: test-design-qa
+    description: "System-level test design: Test execution recipe, coverage plan, Sprint 0 setup for QA team"
+    path: "{output_folder}/test-design-qa.md"
+    mode: system-level
+    audience: qa
+
+  # Epic-Level Mode (Phase 4) - ONE document (unchanged)
  - id: epic-level
    description: "Epic-level test plan (Phase 4)"
    path: "{output_folder}/test-design-epic-{epic_num}.md"
-default_output_file: "{output_folder}/test-design-epic-{epic_num}.md"
+    mode: epic-level
+# Note: No default_output_file - mode detection determines which outputs to write

 # Required tools
 required_tools:
--- a/test/helpers/fixtures.js
+++ b/test/helpers/fixtures.js
@ -0,0 +1,83 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import yaml from 'yaml';
+import xml2js from 'xml2js';
+
+// Get the directory of this module
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Load a fixture file
+ * @param {string} fixturePath - Relative path to fixture from test/fixtures/
+ * @returns {Promise<string>} File content
+ */
+export async function loadFixture(fixturePath) {
+  const fullPath = path.join(__dirname, '..', 'fixtures', fixturePath);
+  return fs.readFile(fullPath, 'utf8');
+}
+
+/**
+ * Load a YAML fixture
+ * @param {string} fixturePath - Relative path to YAML fixture
+ * @returns {Promise<Object>} Parsed YAML object
+ */
+export async function loadYamlFixture(fixturePath) {
+  const content = await loadFixture(fixturePath);
+  return yaml.parse(content);
+}
+
+/**
+ * Load an XML fixture
+ * @param {string} fixturePath - Relative path to XML fixture
+ * @returns {Promise<Object>} Parsed XML object
+ */
+export async function loadXmlFixture(fixturePath) {
+  const content = await loadFixture(fixturePath);
+  return xml2js.parseStringPromise(content);
+}
+
+/**
+ * Load a JSON fixture
+ * @param {string} fixturePath - Relative path to JSON fixture
+ * @returns {Promise<Object>} Parsed JSON object
+ */
+export async function loadJsonFixture(fixturePath) {
+  const content = await loadFixture(fixturePath);
+  return JSON.parse(content);
+}
+
+/**
+ * Check if a fixture file exists
+ * @param {string} fixturePath - Relative path to fixture
+ * @returns {Promise<boolean>} True if fixture exists
+ */
+export async function fixtureExists(fixturePath) {
+  const fullPath = path.join(__dirname, '..', 'fixtures', fixturePath);
+  return fs.pathExists(fullPath);
+}
+
+/**
+ * Get the full path to a fixture
+ * @param {string} fixturePath - Relative path to fixture
+ * @returns {string} Full path to fixture
+ */
+export function getFixturePath(fixturePath) {
+  return path.join(__dirname, '..', 'fixtures', fixturePath);
+}
+
+/**
+ * Create a test file in a temporary directory
+ * (Re-exported from temp-dir for convenience)
+ * @param {string} tmpDir - Temporary directory path
+ * @param {string} relativePath - Relative path for the file
+ * @param {string} content - File content
+ * @returns {Promise<string>} Full path to the created file
+ */
+export async function createTestFile(tmpDir, relativePath, content) {
+  const fullPath = path.join(tmpDir, relativePath);
+  await fs.ensureDir(path.dirname(fullPath));
+  await fs.writeFile(fullPath, content, 'utf8');
+  return fullPath;
+}
--- a/test/helpers/temp-dir.js
+++ b/test/helpers/temp-dir.js
@ -0,0 +1,82 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+
+/**
+ * Create a temporary directory for testing
+ * @param {string} prefix - Prefix for the directory name
+ * @returns {Promise<string>} Path to the created temporary directory
+ */
+export async function createTempDir(prefix = 'bmad-test-') {
+  const tmpDir = path.join(os.tmpdir(), `${prefix}${randomUUID()}`);
+  await fs.ensureDir(tmpDir);
+  return tmpDir;
+}
+
+/**
+ * Clean up a temporary directory
+ * @param {string} tmpDir - Path to the temporary directory
+ * @returns {Promise<void>}
+ */
+export async function cleanupTempDir(tmpDir) {
+  if (await fs.pathExists(tmpDir)) {
+    await fs.remove(tmpDir);
+  }
+}
+
+/**
+ * Execute a test function with a temporary directory
+ * Automatically creates and cleans up the directory
+ * @param {Function} testFn - Test function that receives the temp directory path
+ * @returns {Promise<void>}
+ */
+export async function withTempDir(testFn) {
+  const tmpDir = await createTempDir();
+  try {
+    await testFn(tmpDir);
+  } finally {
+    await cleanupTempDir(tmpDir);
+  }
+}
+
+/**
+ * Create a test file in a temporary directory
+ * @param {string} tmpDir - Temporary directory path
+ * @param {string} relativePath - Relative path for the file
+ * @param {string} content - File content
+ * @returns {Promise<string>} Full path to the created file
+ */
+export async function createTestFile(tmpDir, relativePath, content) {
+  const fullPath = path.join(tmpDir, relativePath);
+  await fs.ensureDir(path.dirname(fullPath));
+  await fs.writeFile(fullPath, content, 'utf8');
+  return fullPath;
+}
+
+/**
+ * Create multiple test files in a temporary directory
+ * @param {string} tmpDir - Temporary directory path
+ * @param {Object} files - Object mapping relative paths to content
+ * @returns {Promise<string[]>} Array of created file paths
+ */
+export async function createTestFiles(tmpDir, files) {
+  const paths = [];
+  for (const [relativePath, content] of Object.entries(files)) {
+    const fullPath = await createTestFile(tmpDir, relativePath, content);
+    paths.push(fullPath);
+  }
+  return paths;
+}
+
+/**
+ * Create a test directory structure
+ * @param {string} tmpDir - Temporary directory path
+ * @param {string[]} dirs - Array of relative directory paths
+ * @returns {Promise<void>}
+ */
+export async function createTestDirs(tmpDir, dirs) {
+  for (const dir of dirs) {
+    await fs.ensureDir(path.join(tmpDir, dir));
+  }
+}
--- a/test/setup.js
+++ b/test/setup.js
@ -0,0 +1,26 @@
+import { beforeEach, afterEach } from 'vitest';
+
+// Global test setup
+beforeEach(() => {
+  // Reset environment variables to prevent test pollution
+  // Store original env for restoration
+  if (!globalThis.__originalEnv) {
+    globalThis.__originalEnv = { ...process.env };
+  }
+});
+
+afterEach(async () => {
+  // Restore original environment variables
+  if (globalThis.__originalEnv) {
+    process.env = { ...globalThis.__originalEnv };
+  }
+
+  // Any global cleanup can go here
+});
+
+// Increase timeout for file system operations
+// (Individual tests can override this if needed)
+const DEFAULT_TIMEOUT = 10_000; // 10 seconds
+
+// Make timeout available globally
+globalThis.DEFAULT_TEST_TIMEOUT = DEFAULT_TIMEOUT;
--- a/test/unit/config/config.test.js
+++ b/test/unit/config/config.test.js
@ -0,0 +1,428 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { Config } from '../../../tools/cli/lib/config.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+import yaml from 'yaml';
+
+describe('Config', () => {
+  let tmpDir;
+  let config;
+
+  beforeEach(async () => {
+    tmpDir = await createTempDir();
+    config = new Config();
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tmpDir);
+  });
+
+  describe('loadYaml()', () => {
+    it('should load and parse YAML file', async () => {
+      const yamlContent = {
+        key1: 'value1',
+        key2: { nested: 'value2' },
+        array: [1, 2, 3],
+      };
+
+      const configPath = path.join(tmpDir, 'config.yaml');
+      await fs.writeFile(configPath, yaml.stringify(yamlContent));
+
+      const result = await config.loadYaml(configPath);
+
+      expect(result).toEqual(yamlContent);
+    });
+
+    it('should throw error for non-existent file', async () => {
+      const nonExistent = path.join(tmpDir, 'missing.yaml');
+
+      await expect(config.loadYaml(nonExistent)).rejects.toThrow('Configuration file not found');
+    });
+
+    it('should handle Unicode content', async () => {
+      const yamlContent = {
+        chinese: '测试',
+        russian: 'Тест',
+        japanese: 'テスト',
+      };
+
+      const configPath = path.join(tmpDir, 'unicode.yaml');
+      await fs.writeFile(configPath, yaml.stringify(yamlContent));
+
+      const result = await config.loadYaml(configPath);
+
+      expect(result.chinese).toBe('测试');
+      expect(result.russian).toBe('Тест');
+      expect(result.japanese).toBe('テスト');
+    });
+  });
+
+  // Note: saveYaml() is not tested because it uses yaml.dump() which doesn't exist
+  // in yaml 2.7.0 (should use yaml.stringify). This method is never called in production
+  // and represents dead code with a latent bug.
+
+  describe('processConfig()', () => {
+    it('should replace {project-root} placeholder', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Root is {project-root}/bmad');
+
+      await config.processConfig(configPath, { root: '/home/user/project' });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toBe('Root is /home/user/project/bmad');
+    });
+
+    it('should replace {module} placeholder', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Module: {module}');
+
+      await config.processConfig(configPath, { module: 'bmm' });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toBe('Module: bmm');
+    });
+
+    it('should replace {version} placeholder with package version', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Version: {version}');
+
+      await config.processConfig(configPath);
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toMatch(/Version: \d+\.\d+\.\d+/); // Semver format
+    });
+
+    it('should replace {date} placeholder with current date', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Date: {date}');
+
+      await config.processConfig(configPath);
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toMatch(/Date: \d{4}-\d{2}-\d{2}/); // YYYY-MM-DD
+    });
+
+    it('should replace multiple placeholders', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Root: {project-root}, Module: {module}, Version: {version}');
+
+      await config.processConfig(configPath, {
+        root: '/project',
+        module: 'test',
+      });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toContain('Root: /project');
+      expect(content).toContain('Module: test');
+      expect(content).toMatch(/Version: \d+\.\d+/);
+    });
+
+    it('should replace custom placeholders', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Custom: {custom-placeholder}');
+
+      await config.processConfig(configPath, { '{custom-placeholder}': 'custom-value' });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toBe('Custom: custom-value');
+    });
+
+    it('should escape regex special characters in placeholders', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Path: {project-root}/test');
+
+      // Test that {project-root} doesn't get interpreted as regex
+      await config.processConfig(configPath, {
+        root: '/path/with/special$chars^',
+      });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toBe('Path: /path/with/special$chars^/test');
+    });
+
+    it('should handle placeholders with regex metacharacters in values', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, 'Value: {placeholder}');
+
+      await config.processConfig(configPath, {
+        '{placeholder}': String.raw`value with $1 and \backslash`,
+      });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toBe(String.raw`Value: value with $1 and \backslash`);
+    });
+
+    it('should replace all occurrences of placeholder', async () => {
+      const configPath = path.join(tmpDir, 'config.txt');
+      await fs.writeFile(configPath, '{module} is here and {module} is there and {module} everywhere');
+
+      await config.processConfig(configPath, { module: 'BMM' });
+
+      const content = await fs.readFile(configPath, 'utf8');
+      expect(content).toBe('BMM is here and BMM is there and BMM everywhere');
+    });
+  });
+
+  describe('deepMerge()', () => {
+    it('should merge shallow objects', () => {
+      const target = { a: 1, b: 2 };
+      const source = { b: 3, c: 4 };
+
+      const result = config.deepMerge(target, source);
+
+      expect(result).toEqual({ a: 1, b: 3, c: 4 });
+    });
+
+    it('should merge nested objects', () => {
+      const target = { level1: { a: 1, b: 2 } };
+      const source = { level1: { b: 3, c: 4 } };
+
+      const result = config.deepMerge(target, source);
+
+      expect(result.level1).toEqual({ a: 1, b: 3, c: 4 });
+    });
+
+    it('should not merge arrays (just replace)', () => {
+      const target = { items: [1, 2, 3] };
+      const source = { items: [4, 5] };
+
+      const result = config.deepMerge(target, source);
+
+      expect(result.items).toEqual([4, 5]); // Replaced, not merged
+    });
+
+    it('should handle null values', () => {
+      const target = { a: 'value', b: null };
+      const source = { a: null, c: 'new' };
+
+      const result = config.deepMerge(target, source);
+
+      expect(result).toEqual({ a: null, b: null, c: 'new' });
+    });
+
+    it('should not mutate original objects', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+
+      config.deepMerge(target, source);
+
+      expect(target).toEqual({ a: 1 });
+      expect(source).toEqual({ b: 2 });
+    });
+  });
+
+  describe('mergeConfigs()', () => {
+    it('should delegate to deepMerge', () => {
+      const base = { setting1: 'base' };
+      const override = { setting2: 'override' };
+
+      const result = config.mergeConfigs(base, override);
+
+      expect(result).toEqual({ setting1: 'base', setting2: 'override' });
+    });
+  });
+
+  describe('isObject()', () => {
+    it('should return true for plain objects', () => {
+      expect(config.isObject({})).toBe(true);
+      expect(config.isObject({ key: 'value' })).toBe(true);
+    });
+
+    it('should return false for arrays', () => {
+      expect(config.isObject([])).toBe(false);
+    });
+
+    it('should return false for null', () => {
+      expect(config.isObject(null)).toBeFalsy();
+    });
+
+    it('should return false for primitives', () => {
+      expect(config.isObject('string')).toBe(false);
+      expect(config.isObject(42)).toBe(false);
+    });
+  });
+
+  describe('getValue() and setValue()', () => {
+    it('should get value by dot notation path', () => {
+      const obj = {
+        level1: {
+          level2: {
+            value: 'test',
+          },
+        },
+      };
+
+      const result = config.getValue(obj, 'level1.level2.value');
+
+      expect(result).toBe('test');
+    });
+
+    it('should set value by dot notation path', () => {
+      const obj = {
+        level1: {
+          level2: {},
+        },
+      };
+
+      config.setValue(obj, 'level1.level2.value', 'new value');
+
+      expect(obj.level1.level2.value).toBe('new value');
+    });
+
+    it('should return default value for non-existent path', () => {
+      const obj = { a: { b: 'value' } };
+
+      const result = config.getValue(obj, 'a.c.d', 'default');
+
+      expect(result).toBe('default');
+    });
+
+    it('should return null default when path not found', () => {
+      const obj = { a: { b: 'value' } };
+
+      const result = config.getValue(obj, 'a.c.d');
+
+      expect(result).toBeNull();
+    });
+
+    it('should handle simple (non-nested) paths', () => {
+      const obj = { key: 'value' };
+
+      expect(config.getValue(obj, 'key')).toBe('value');
+
+      config.setValue(obj, 'newKey', 'newValue');
+      expect(obj.newKey).toBe('newValue');
+    });
+
+    it('should create intermediate objects when setting deep paths', () => {
+      const obj = {};
+
+      config.setValue(obj, 'a.b.c.d', 'deep value');
+
+      expect(obj.a.b.c.d).toBe('deep value');
+    });
+  });
+
+  describe('validateConfig()', () => {
+    it('should validate required fields', () => {
+      const cfg = { field1: 'value1' };
+      const schema = {
+        required: ['field1', 'field2'],
+      };
+
+      const result = config.validateConfig(cfg, schema);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors).toContain('Missing required field: field2');
+    });
+
+    it('should pass when all required fields present', () => {
+      const cfg = { field1: 'value1', field2: 'value2' };
+      const schema = {
+        required: ['field1', 'field2'],
+      };
+
+      const result = config.validateConfig(cfg, schema);
+
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it('should validate field types', () => {
+      const cfg = {
+        stringField: 'text',
+        numberField: '42', // Wrong type
+        arrayField: [1, 2, 3],
+        objectField: 'not-object', // Wrong type
+        boolField: true,
+      };
+
+      const schema = {
+        properties: {
+          stringField: { type: 'string' },
+          numberField: { type: 'number' },
+          arrayField: { type: 'array' },
+          objectField: { type: 'object' },
+          boolField: { type: 'boolean' },
+        },
+      };
+
+      const result = config.validateConfig(cfg, schema);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes('numberField'))).toBe(true);
+      expect(result.errors.some((e) => e.includes('objectField'))).toBe(true);
+    });
+
+    it('should validate enum values', () => {
+      const cfg = { level: 'expert' };
+      const schema = {
+        properties: {
+          level: { type: 'string', enum: ['beginner', 'intermediate', 'advanced'] },
+        },
+      };
+
+      const result = config.validateConfig(cfg, schema);
+
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.includes('must be one of'))).toBe(true);
+    });
+
+    it('should pass validation for valid enum value', () => {
+      const cfg = { level: 'intermediate' };
+      const schema = {
+        properties: {
+          level: { type: 'string', enum: ['beginner', 'intermediate', 'advanced'] },
+        },
+      };
+
+      const result = config.validateConfig(cfg, schema);
+
+      expect(result.valid).toBe(true);
+    });
+
+    it('should return warnings array', () => {
+      const cfg = { field: 'value' };
+      const schema = { required: ['field'] };
+
+      const result = config.validateConfig(cfg, schema);
+
+      expect(result.warnings).toBeDefined();
+      expect(Array.isArray(result.warnings)).toBe(true);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty YAML file', async () => {
+      const configPath = path.join(tmpDir, 'empty.yaml');
+      await fs.writeFile(configPath, '');
+
+      const result = await config.loadYaml(configPath);
+
+      expect(result).toBeNull(); // Empty YAML parses to null
+    });
+
+    it('should handle YAML with only comments', async () => {
+      const configPath = path.join(tmpDir, 'comments.yaml');
+      await fs.writeFile(configPath, '# Just a comment\n# Another comment\n');
+
+      const result = await config.loadYaml(configPath);
+
+      expect(result).toBeNull();
+    });
+
+    it('should handle very deep object nesting', () => {
+      const deep = {
+        l1: { l2: { l3: { l4: { l5: { l6: { l7: { l8: { value: 'deep' } } } } } } } },
+      };
+      const override = {
+        l1: { l2: { l3: { l4: { l5: { l6: { l7: { l8: { value: 'updated' } } } } } } } },
+      };
+
+      const result = config.deepMerge(deep, override);
+
+      expect(result.l1.l2.l3.l4.l5.l6.l7.l8.value).toBe('updated');
+    });
+  });
+});
--- a/test/unit/core/dependency-resolver-advanced.test.js
+++ b/test/unit/core/dependency-resolver-advanced.test.js
@ -0,0 +1,558 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { DependencyResolver } from '../../../tools/cli/installers/lib/core/dependency-resolver.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+describe('DependencyResolver - Advanced Scenarios', () => {
+  let tmpDir;
+  let bmadDir;
+
+  beforeEach(async () => {
+    tmpDir = await createTempDir();
+    bmadDir = path.join(tmpDir, 'src');
+    await fs.ensureDir(path.join(bmadDir, 'core', 'agents'));
+    await fs.ensureDir(path.join(bmadDir, 'core', 'tasks'));
+    await fs.ensureDir(path.join(bmadDir, 'core', 'templates'));
+    await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'agents'));
+    await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'tasks'));
+    await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'templates'));
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tmpDir);
+  });
+
+  describe('module path resolution', () => {
+    it('should resolve bmad/bmm/tasks/task.md (module path)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["{project-root}/bmad/bmm/tasks/analyze.md"]
+---
+<agent>Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'modules/bmm/tasks/analyze.md', 'BMM Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('bmm'))).toBe(true);
+      expect([...result.allFiles].some((f) => f.includes('analyze.md'))).toBe(true);
+    });
+
+    it('should handle glob in module path bmad/bmm/tasks/*.md', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["{project-root}/bmad/bmm/tasks/*.md"]
+---
+<agent>Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'modules/bmm/tasks/task1.md', 'Task 1');
+      await createTestFile(bmadDir, 'modules/bmm/tasks/task2.md', 'Task 2');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']); // Include bmm module
+
+      // Should resolve glob pattern
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should handle non-existent module path gracefully', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["{project-root}/bmad/nonexistent/tasks/task.md"]
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should not crash, just skip missing dependency
+      expect(result.primaryFiles).toHaveLength(1);
+    });
+  });
+
+  describe('relative glob patterns', () => {
+    it('should resolve relative glob patterns ../tasks/*.md', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["../tasks/*.md"]
+---
+<agent>Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task1.md', 'Task 1');
+      await createTestFile(bmadDir, 'core/tasks/task2.md', 'Task 2');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(3);
+    });
+
+    it('should handle glob pattern with no matches', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["../tasks/nonexistent-*.md"]
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should handle gracefully - just the agent
+      expect(result.primaryFiles).toHaveLength(1);
+    });
+
+    it('should handle glob in non-existent directory', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["../nonexistent/*.md"]
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should handle gracefully
+      expect(result.primaryFiles).toHaveLength(1);
+    });
+  });
+
+  describe('template dependencies', () => {
+    it('should resolve template with {project-root} prefix', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Agent</agent>');
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task.md',
+        `---
+template: "{project-root}/bmad/core/templates/form.yaml"
+---
+Task content`,
+      );
+      await createTestFile(bmadDir, 'core/templates/form.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Template dependency should be resolved
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should resolve template from module path', async () => {
+      await createTestFile(bmadDir, 'modules/bmm/agents/agent.md', '<agent>BMM Agent</agent>');
+      await createTestFile(
+        bmadDir,
+        'modules/bmm/tasks/task.md',
+        `---
+template: "{project-root}/bmad/bmm/templates/prd-template.yaml"
+---
+Task`,
+      );
+      await createTestFile(bmadDir, 'modules/bmm/templates/prd-template.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      // Should resolve files from BMM module
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should handle missing template gracefully', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task.md',
+        `---
+template: "../templates/missing.yaml"
+---
+Task`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should not crash
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('bmad-path type resolution', () => {
+    it('should resolve bmad-path dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+<command exec="bmad/core/tasks/analyze" />
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/analyze.md', 'Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('analyze.md'))).toBe(true);
+    });
+
+    it('should resolve bmad-path for module files', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+<command exec="bmad/bmm/tasks/create-prd" />
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'modules/bmm/tasks/create-prd.md', 'PRD Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('create-prd.md'))).toBe(true);
+    });
+
+    it('should handle non-existent bmad-path gracefully', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+<command exec="bmad/core/tasks/missing" />
+</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should not crash
+      expect(result.primaryFiles).toHaveLength(1);
+    });
+  });
+
+  describe('command resolution with modules', () => {
+    it('should search multiple modules for @task-name', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+Use @task-custom-task
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'modules/bmm/tasks/custom-task.md', 'Custom Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      expect([...result.allFiles].some((f) => f.includes('custom-task.md'))).toBe(true);
+    });
+
+    it('should search multiple modules for @agent-name', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/main.md',
+        `<agent>
+Use @agent-pm
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'modules/bmm/agents/pm.md', '<agent>PM</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      expect([...result.allFiles].some((f) => f.includes('pm.md'))).toBe(true);
+    });
+
+    it('should handle bmad/ path with 4+ segments', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+Reference bmad/core/tasks/nested/deep/task
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/nested/deep/task.md', 'Deep task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Implementation may or may not support deeply nested paths in commands
+      // Just verify it doesn't crash
+      expect(result.primaryFiles.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should handle bmad path with .md extension already', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+Use bmad/core/tasks/task.md explicitly
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('task.md'))).toBe(true);
+    });
+  });
+
+  describe('verbose mode', () => {
+    it('should include console output when verbose is true', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Test</agent>');
+
+      const resolver = new DependencyResolver();
+
+      // Mock console.log to capture output
+      const logs = [];
+      const originalLog = console.log;
+      console.log = (...args) => logs.push(args.join(' '));
+
+      await resolver.resolve(bmadDir, [], { verbose: true });
+
+      console.log = originalLog;
+
+      // Should have logged something in verbose mode
+      expect(logs.length).toBeGreaterThan(0);
+    });
+
+    it('should not log when verbose is false', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Test</agent>');
+
+      const resolver = new DependencyResolver();
+
+      const logs = [];
+      const originalLog = console.log;
+      console.log = (...args) => logs.push(args.join(' '));
+
+      await resolver.resolve(bmadDir, [], { verbose: false });
+
+      console.log = originalLog;
+
+      // Should not have logged in non-verbose mode
+      // (There might be warns but no regular logs)
+      expect(logs.length).toBe(0);
+    });
+  });
+
+  describe('createWebBundle()', () => {
+    it('should create bundle with metadata', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Agent</agent>');
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+
+      const resolver = new DependencyResolver();
+      const resolution = await resolver.resolve(bmadDir, []);
+
+      const bundle = await resolver.createWebBundle(resolution);
+
+      expect(bundle.metadata).toBeDefined();
+      expect(bundle.metadata.modules).toContain('core');
+      expect(bundle.metadata.totalFiles).toBeGreaterThan(0);
+    });
+
+    it('should organize bundle by file type', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Agent</agent>');
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+      await createTestFile(bmadDir, 'core/templates/template.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const resolution = await resolver.resolve(bmadDir, []);
+
+      const bundle = await resolver.createWebBundle(resolution);
+
+      expect(bundle.agents).toBeDefined();
+      expect(bundle.tasks).toBeDefined();
+      expect(bundle.templates).toBeDefined();
+    });
+  });
+
+  describe('single string dependency (not array)', () => {
+    it('should handle single string dependency (converted to array)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: "{project-root}/bmad/core/tasks/task.md"
+---
+<agent>Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Single string should be converted to array internally
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it('should handle single string template', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task.md',
+        `---
+template: "../templates/form.yaml"
+---
+Task`,
+      );
+      await createTestFile(bmadDir, 'core/templates/form.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('form.yaml'))).toBe(true);
+    });
+  });
+
+  describe('missing dependency tracking', () => {
+    it('should track missing relative file dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["../tasks/missing-file.md"]
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Missing dependency should be tracked
+      expect(result.missing.length).toBeGreaterThanOrEqual(0);
+      // Should not crash
+      expect(result).toBeDefined();
+    });
+  });
+
+  describe('reportResults()', () => {
+    it('should report results with file counts', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent1.md', '<agent>1</agent>');
+      await createTestFile(bmadDir, 'core/agents/agent2.md', '<agent>2</agent>');
+      await createTestFile(bmadDir, 'core/tasks/task1.md', 'Task 1');
+      await createTestFile(bmadDir, 'core/tasks/task2.md', 'Task 2');
+      await createTestFile(bmadDir, 'core/templates/template.yaml', 'Template');
+
+      const resolver = new DependencyResolver();
+
+      // Mock console.log
+      const logs = [];
+      const originalLog = console.log;
+      console.log = (...args) => logs.push(args.join(' '));
+
+      const result = await resolver.resolve(bmadDir, [], { verbose: true });
+
+      console.log = originalLog;
+
+      // Should have reported module statistics
+      expect(logs.some((log) => log.includes('CORE'))).toBe(true);
+      expect(logs.some((log) => log.includes('Agents:'))).toBe(true);
+      expect(logs.some((log) => log.includes('Tasks:'))).toBe(true);
+    });
+
+    it('should report missing dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["../tasks/missing.md"]
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+
+      const logs = [];
+      const originalLog = console.log;
+      console.log = (...args) => logs.push(args.join(' '));
+
+      await resolver.resolve(bmadDir, [], { verbose: true });
+
+      console.log = originalLog;
+
+      // May log warning about missing dependencies
+      expect(logs.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('file without .md extension in command', () => {
+    it('should add .md extension to bmad/ commands without extension', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+Use bmad/core/tasks/analyze without extension
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/analyze.md', 'Analyze');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('analyze.md'))).toBe(true);
+    });
+  });
+
+  describe('module structure detection', () => {
+    it('should detect source directory structure (src/)', async () => {
+      // Default structure already uses src/
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Core</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should detect installed directory structure (no src/)', async () => {
+      // Create installed structure
+      const installedDir = path.join(tmpDir, 'installed');
+      await fs.ensureDir(path.join(installedDir, 'core', 'agents'));
+      await fs.ensureDir(path.join(installedDir, 'modules', 'bmm', 'agents'));
+      await createTestFile(installedDir, 'core/agents/agent.md', '<agent>Core</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(installedDir, []);
+
+      expect(result.primaryFiles.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe('dependency deduplication', () => {
+    it('should not include same file twice', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent1.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/shared.md"]
+---
+<agent>1</agent>`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent2.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/shared.md"]
+---
+<agent>2</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/shared.md', 'Shared');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should have 2 agents + 1 shared task = 3 unique files
+      expect(result.allFiles).toHaveLength(3);
+    });
+  });
+});
--- a/test/unit/core/dependency-resolver.test.js
+++ b/test/unit/core/dependency-resolver.test.js
@ -0,0 +1,796 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { DependencyResolver } from '../../../tools/cli/installers/lib/core/dependency-resolver.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+describe('DependencyResolver', () => {
+  let tmpDir;
+  let bmadDir;
+
+  beforeEach(async () => {
+    tmpDir = await createTempDir();
+    // Create structure: tmpDir/src/core and tmpDir/src/modules/
+    bmadDir = path.join(tmpDir, 'src');
+    await fs.ensureDir(path.join(bmadDir, 'core', 'agents'));
+    await fs.ensureDir(path.join(bmadDir, 'core', 'tasks'));
+    await fs.ensureDir(path.join(bmadDir, 'core', 'templates'));
+    await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'agents'));
+    await fs.ensureDir(path.join(bmadDir, 'modules', 'bmm', 'tasks'));
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tmpDir);
+  });
+
+  describe('basic resolution', () => {
+    it('should resolve core agents with no dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/simple.md',
+        `---
+name: simple
+---
+<agent>Simple agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles).toHaveLength(1);
+      expect(result.primaryFiles[0].type).toBe('agent');
+      expect(result.primaryFiles[0].module).toBe('core');
+      expect(result.allFiles).toHaveLength(1);
+    });
+
+    it('should resolve multiple agents from same module', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent1.md', '<agent>Agent 1</agent>');
+      await createTestFile(bmadDir, 'core/agents/agent2.md', '<agent>Agent 2</agent>');
+      await createTestFile(bmadDir, 'core/agents/agent3.md', '<agent>Agent 3</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles).toHaveLength(3);
+      expect(result.allFiles).toHaveLength(3);
+    });
+
+    it('should always include core module', async () => {
+      await createTestFile(bmadDir, 'core/agents/core-agent.md', '<agent>Core</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      // Core should be included even though only 'bmm' was requested
+      expect(result.byModule.core).toBeDefined();
+    });
+
+    it('should skip agents with localskip="true"', async () => {
+      await createTestFile(bmadDir, 'core/agents/normal.md', '<agent>Normal agent</agent>');
+      await createTestFile(bmadDir, 'core/agents/webonly.md', '<agent localskip="true">Web only agent</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles).toHaveLength(1);
+      expect(result.primaryFiles[0].name).toBe('normal');
+    });
+  });
+
+  describe('path resolution variations', () => {
+    it('should resolve {project-root}/bmad/core/tasks/foo.md dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task.md"]
+---
+<agent>Agent with task dependency</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task content');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(2);
+      expect(result.dependencies.size).toBeGreaterThan(0);
+      expect([...result.dependencies].some((d) => d.includes('task.md'))).toBe(true);
+    });
+
+    it('should resolve relative path dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+template: "../templates/template.yaml"
+---
+<agent>Agent with template</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/templates/template.yaml', 'template: data');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(2);
+      expect([...result.dependencies].some((d) => d.includes('template.yaml'))).toBe(true);
+    });
+
+    it('should resolve glob pattern dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/*.md"]
+---
+<agent>Agent with multiple tasks</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task1.md', 'Task 1');
+      await createTestFile(bmadDir, 'core/tasks/task2.md', 'Task 2');
+      await createTestFile(bmadDir, 'core/tasks/task3.md', 'Task 3');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should find agent + 3 tasks
+      expect(result.allFiles).toHaveLength(4);
+    });
+
+    it('should resolve array of dependencies', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies:
+  - "{project-root}/bmad/core/tasks/task1.md"
+  - "{project-root}/bmad/core/tasks/task2.md"
+  - "../templates/template.yaml"
+---
+<agent>Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task1.md', 'Task 1');
+      await createTestFile(bmadDir, 'core/tasks/task2.md', 'Task 2');
+      await createTestFile(bmadDir, 'core/templates/template.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(4); // agent + 2 tasks + template
+    });
+  });
+
+  describe('command reference resolution', () => {
+    it('should resolve @task-name references', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+Use @task-analyze for analysis
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/analyze.md', 'Analyze task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(2);
+      expect([...result.allFiles].some((f) => f.includes('analyze.md'))).toBe(true);
+    });
+
+    it('should resolve @agent-name references', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/main.md',
+        `<agent>
+Reference @agent-helper for help
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/agents/helper.md', '<agent>Helper</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(2);
+      expect([...result.allFiles].some((f) => f.includes('helper.md'))).toBe(true);
+    });
+
+    it('should resolve bmad/module/type/name references', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+See bmad/core/tasks/review
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/review.md', 'Review task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('review.md'))).toBe(true);
+    });
+  });
+
+  describe('exec and tmpl attribute parsing', () => {
+    it('should parse exec attributes from command tags', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+<command exec="{project-root}/bmad/core/tasks/task.md" />
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('task.md'))).toBe(true);
+    });
+
+    it('should parse tmpl attributes from command tags', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+<command tmpl="../templates/form.yaml" />
+</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/templates/form.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect([...result.allFiles].some((f) => f.includes('form.yaml'))).toBe(true);
+    });
+
+    it('should ignore exec="*" wildcard', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `<agent>
+<command exec="*" description="Dynamic" />
+</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should only have the agent itself
+      expect(result.primaryFiles).toHaveLength(1);
+    });
+  });
+
+  describe('multi-pass dependency resolution', () => {
+    it('should resolve single-level dependencies (A→B)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-b.md"]
+---
+<agent>Agent A</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task-b.md', 'Task B');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(2);
+      // Primary files includes both agents and tasks from selected modules
+      expect(result.primaryFiles.length).toBeGreaterThanOrEqual(1);
+      expect(result.dependencies.size).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should resolve two-level dependencies (A→B→C)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-b.md"]
+---
+<agent>Agent A</agent>`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-b.md',
+        `---
+template: "../templates/template-c.yaml"
+---
+Task B content`,
+      );
+      await createTestFile(bmadDir, 'core/templates/template-c.yaml', 'template: data');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(3);
+      // Primary files includes agents and tasks
+      expect(result.primaryFiles.length).toBeGreaterThanOrEqual(1);
+      // Total dependencies (direct + transitive) should be at least 2
+      const totalDeps = result.dependencies.size + result.transitiveDependencies.size;
+      expect(totalDeps).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should resolve three-level dependencies (A→B→C→D)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-b.md"]
+---
+<agent>A</agent>`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-b.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-c.md"]
+---
+Task B`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-c.md',
+        `---
+template: "../templates/template-d.yaml"
+---
+Task C`,
+      );
+      await createTestFile(bmadDir, 'core/templates/template-d.yaml', 'Template D');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(4);
+    });
+
+    it('should resolve multiple branches (A→B, A→C)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies:
+  - "{project-root}/bmad/core/tasks/task-b.md"
+  - "{project-root}/bmad/core/tasks/task-c.md"
+---
+<agent>A</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task-b.md', 'Task B');
+      await createTestFile(bmadDir, 'core/tasks/task-c.md', 'Task C');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.allFiles).toHaveLength(3);
+      expect(result.dependencies.size).toBe(2);
+    });
+
+    it('should deduplicate diamond pattern (A→B,C; B,C→D)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies:
+  - "{project-root}/bmad/core/tasks/task-b.md"
+  - "{project-root}/bmad/core/tasks/task-c.md"
+---
+<agent>A</agent>`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-b.md',
+        `---
+template: "../templates/shared.yaml"
+---
+Task B`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-c.md',
+        `---
+template: "../templates/shared.yaml"
+---
+Task C`,
+      );
+      await createTestFile(bmadDir, 'core/templates/shared.yaml', 'Shared template');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // A + B + C + shared = 4 unique files (D appears twice but should be deduped)
+      expect(result.allFiles).toHaveLength(4);
+    });
+  });
+
+  describe('circular dependency detection', () => {
+    it('should detect direct circular dependency (A→B→A)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-b.md"]
+---
+<agent>A</agent>`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-b.md',
+        `---
+dependencies: ["{project-root}/bmad/core/agents/agent-a.md"]
+---
+Task B`,
+      );
+
+      const resolver = new DependencyResolver();
+
+      // Should not hang or crash
+      const resultPromise = resolver.resolve(bmadDir, []);
+      await expect(resultPromise).resolves.toBeDefined();
+
+      const result = await resultPromise;
+      // Should process both files without infinite loop
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(2);
+    }, 5000); // 5 second timeout to ensure no infinite loop
+
+    it('should detect indirect circular dependency (A→B→C→A)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-b.md"]
+---
+<agent>A</agent>`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-b.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/task-c.md"]
+---
+Task B`,
+      );
+      await createTestFile(
+        bmadDir,
+        'core/tasks/task-c.md',
+        `---
+dependencies: ["{project-root}/bmad/core/agents/agent-a.md"]
+---
+Task C`,
+      );
+
+      const resolver = new DependencyResolver();
+      const resultPromise = resolver.resolve(bmadDir, []);
+
+      await expect(resultPromise).resolves.toBeDefined();
+      const result = await resultPromise;
+
+      // Should include all 3 files without duplicates
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(3);
+    }, 5000);
+
+    it('should handle self-reference (A→A)', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent-a.md',
+        `---
+dependencies: ["{project-root}/bmad/core/agents/agent-a.md"]
+---
+<agent>A</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Should include the file once, not infinite times
+      expect(result.allFiles).toHaveLength(1);
+    }, 5000);
+  });
+
+  describe('command reference parsing', () => {
+    describe('parseCommandReferences()', () => {
+      it('should extract @task- references', () => {
+        const resolver = new DependencyResolver();
+        const content = 'Use @task-analyze for analysis\nThen @task-review';
+
+        const refs = resolver.parseCommandReferences(content);
+
+        expect(refs).toContain('@task-analyze');
+        expect(refs).toContain('@task-review');
+      });
+
+      it('should extract @agent- references', () => {
+        const resolver = new DependencyResolver();
+        const content = 'Call @agent-architect then @agent-developer';
+
+        const refs = resolver.parseCommandReferences(content);
+
+        expect(refs).toContain('@agent-architect');
+        expect(refs).toContain('@agent-developer');
+      });
+
+      it('should extract bmad/ path references', () => {
+        const resolver = new DependencyResolver();
+        const content = 'See bmad/core/agents/analyst and bmad/bmm/tasks/review';
+
+        const refs = resolver.parseCommandReferences(content);
+
+        expect(refs).toContain('bmad/core/agents/analyst');
+        expect(refs).toContain('bmad/bmm/tasks/review');
+      });
+
+      it('should extract @bmad- references', () => {
+        const resolver = new DependencyResolver();
+        const content = 'Use @bmad-master command';
+
+        const refs = resolver.parseCommandReferences(content);
+
+        expect(refs).toContain('@bmad-master');
+      });
+
+      it('should handle multiple reference types in same content', () => {
+        const resolver = new DependencyResolver();
+        const content = `
+Use @task-analyze for analysis
+Then run @agent-architect
+Finally check bmad/core/tasks/review
+`;
+
+        const refs = resolver.parseCommandReferences(content);
+
+        expect(refs.length).toBeGreaterThanOrEqual(3);
+      });
+    });
+
+    describe('parseFileReferences()', () => {
+      it('should extract exec attribute paths', () => {
+        const resolver = new DependencyResolver();
+        const content = '<command exec="{project-root}/bmad/core/tasks/foo.md" />';
+
+        const refs = resolver.parseFileReferences(content);
+
+        expect(refs).toContain('/bmad/core/tasks/foo.md');
+      });
+
+      it('should extract tmpl attribute paths', () => {
+        const resolver = new DependencyResolver();
+        const content = '<command tmpl="../templates/bar.yaml" />';
+
+        const refs = resolver.parseFileReferences(content);
+
+        expect(refs).toContain('../templates/bar.yaml');
+      });
+
+      it('should extract relative file paths', () => {
+        const resolver = new DependencyResolver();
+        const content = 'Load "./data/config.json" and "../templates/form.yaml"';
+
+        const refs = resolver.parseFileReferences(content);
+
+        expect(refs).toContain('./data/config.json');
+        expect(refs).toContain('../templates/form.yaml');
+      });
+
+      it('should skip exec="*" wildcards', () => {
+        const resolver = new DependencyResolver();
+        const content = '<command exec="*" description="Dynamic" />';
+
+        const refs = resolver.parseFileReferences(content);
+
+        // Should not include "*"
+        expect(refs).not.toContain('*');
+      });
+    });
+  });
+
+  describe('module organization', () => {
+    it('should organize files by module correctly', async () => {
+      await createTestFile(bmadDir, 'core/agents/core-agent.md', '<agent>Core</agent>');
+      await createTestFile(bmadDir, 'modules/bmm/agents/bmm-agent.md', '<agent>BMM</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      expect(result.byModule.core).toBeDefined();
+      expect(result.byModule.bmm).toBeDefined();
+      expect(result.byModule.core.agents).toHaveLength(1);
+      expect(result.byModule.bmm.agents).toHaveLength(1);
+    });
+
+    it('should categorize files by type', async () => {
+      await createTestFile(bmadDir, 'core/agents/agent.md', '<agent>Agent</agent>');
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+      await createTestFile(bmadDir, 'core/templates/template.yaml', 'template');
+
+      const resolver = new DependencyResolver();
+      const files = [
+        path.join(bmadDir, 'core/agents/agent.md'),
+        path.join(bmadDir, 'core/tasks/task.md'),
+        path.join(bmadDir, 'core/templates/template.yaml'),
+      ];
+
+      const organized = resolver.organizeByModule(bmadDir, new Set(files));
+
+      expect(organized.core.agents).toHaveLength(1);
+      expect(organized.core.tasks).toHaveLength(1);
+      expect(organized.core.templates).toHaveLength(1);
+    });
+
+    it('should treat brain-tech as data, not tasks', async () => {
+      await createTestFile(bmadDir, 'core/tasks/brain-tech/data.csv', 'col1,col2\nval1,val2');
+
+      const resolver = new DependencyResolver();
+      const files = [path.join(bmadDir, 'core/tasks/brain-tech/data.csv')];
+
+      const organized = resolver.organizeByModule(bmadDir, new Set(files));
+
+      expect(organized.core.data).toHaveLength(1);
+      expect(organized.core.tasks).toHaveLength(0);
+    });
+  });
+
+  describe('getModuleFromPath()', () => {
+    it('should extract module from src/core path', () => {
+      const resolver = new DependencyResolver();
+      const filePath = path.join(bmadDir, 'core/agents/agent.md');
+
+      const module = resolver.getModuleFromPath(bmadDir, filePath);
+
+      expect(module).toBe('core');
+    });
+
+    it('should extract module from src/modules/bmm path', () => {
+      const resolver = new DependencyResolver();
+      const filePath = path.join(bmadDir, 'modules/bmm/agents/pm.md');
+
+      const module = resolver.getModuleFromPath(bmadDir, filePath);
+
+      expect(module).toBe('bmm');
+    });
+
+    it('should handle installed directory structure', async () => {
+      // Create installed structure (no src/ prefix)
+      const installedDir = path.join(tmpDir, 'installed');
+      await fs.ensureDir(path.join(installedDir, 'core/agents'));
+      await fs.ensureDir(path.join(installedDir, 'modules/bmm/agents'));
+
+      const resolver = new DependencyResolver();
+
+      const coreFile = path.join(installedDir, 'core/agents/agent.md');
+      const moduleFile = path.join(installedDir, 'modules/bmm/agents/pm.md');
+
+      expect(resolver.getModuleFromPath(installedDir, coreFile)).toBe('core');
+      expect(resolver.getModuleFromPath(installedDir, moduleFile)).toBe('bmm');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle malformed YAML frontmatter', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/bad-yaml.md',
+        `---
+dependencies: [invalid: yaml: here
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+
+      // Should not crash, just warn and continue
+      await expect(resolver.resolve(bmadDir, [])).resolves.toBeDefined();
+    });
+
+    it('should handle backticks in YAML values', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/backticks.md',
+        `---
+name: \`test\`
+dependencies: [\`{project-root}/bmad/core/tasks/task.md\`]
+---
+<agent>Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/task.md', 'Task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      // Backticks should be pre-processed
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it('should handle missing dependencies gracefully', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/missing.md"]
+---
+<agent>Agent</agent>`,
+      );
+      // Don't create missing.md
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles.length).toBeGreaterThanOrEqual(1);
+      // Implementation may or may not track missing dependencies
+      // Just verify it doesn't crash
+      expect(result).toBeDefined();
+    });
+
+    it('should handle empty dependencies array', async () => {
+      await createTestFile(
+        bmadDir,
+        'core/agents/agent.md',
+        `---
+dependencies: []
+---
+<agent>Agent</agent>`,
+      );
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles).toHaveLength(1);
+      expect(result.allFiles).toHaveLength(1);
+    });
+
+    it('should handle missing frontmatter', async () => {
+      await createTestFile(bmadDir, 'core/agents/no-frontmatter.md', '<agent>Agent</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, []);
+
+      expect(result.primaryFiles).toHaveLength(1);
+      expect(result.allFiles).toHaveLength(1);
+    });
+
+    it('should handle non-existent module directory', async () => {
+      // Create at least one core file so core module appears
+      await createTestFile(bmadDir, 'core/agents/core-agent.md', '<agent>Core</agent>');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['nonexistent']);
+
+      // Should include core even though nonexistent module not found
+      expect(result.byModule.core).toBeDefined();
+      expect(result.byModule.nonexistent).toBeUndefined();
+    });
+  });
+
+  describe('cross-module dependencies', () => {
+    it('should resolve dependencies across modules', async () => {
+      await createTestFile(bmadDir, 'core/agents/core-agent.md', '<agent>Core</agent>');
+      await createTestFile(
+        bmadDir,
+        'modules/bmm/agents/bmm-agent.md',
+        `---
+dependencies: ["{project-root}/bmad/core/tasks/shared-task.md"]
+---
+<agent>BMM Agent</agent>`,
+      );
+      await createTestFile(bmadDir, 'core/tasks/shared-task.md', 'Shared task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      // Should include: core agent + bmm agent + shared task
+      expect(result.allFiles.length).toBeGreaterThanOrEqual(3);
+      expect(result.byModule.core).toBeDefined();
+      expect(result.byModule.bmm).toBeDefined();
+    });
+
+    it('should resolve module tasks', async () => {
+      await createTestFile(bmadDir, 'core/agents/core-agent.md', '<agent>Core</agent>');
+      await createTestFile(bmadDir, 'modules/bmm/agents/pm.md', '<agent>PM</agent>');
+      await createTestFile(bmadDir, 'modules/bmm/tasks/create-prd.md', 'Create PRD task');
+
+      const resolver = new DependencyResolver();
+      const result = await resolver.resolve(bmadDir, ['bmm']);
+
+      expect(result.byModule.bmm.agents).toHaveLength(1);
+      expect(result.byModule.bmm.tasks).toHaveLength(1);
+    });
+  });
+});
--- a/test/unit/file-ops/copy-directory.test.js
+++ b/test/unit/file-ops/copy-directory.test.js
@ -0,0 +1,243 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FileOps } from '../../../tools/cli/lib/file-ops.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+describe('FileOps', () => {
+  describe('copyDirectory()', () => {
+    const fileOps = new FileOps();
+    let tmpDir;
+    let sourceDir;
+    let destDir;
+
+    beforeEach(async () => {
+      tmpDir = await createTempDir();
+      sourceDir = path.join(tmpDir, 'source');
+      destDir = path.join(tmpDir, 'dest');
+      await fs.ensureDir(sourceDir);
+      await fs.ensureDir(destDir);
+    });
+
+    afterEach(async () => {
+      await cleanupTempDir(tmpDir);
+    });
+
+    describe('basic copying', () => {
+      it('should copy a single file', async () => {
+        await createTestFile(sourceDir, 'test.txt', 'content');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const destFile = path.join(destDir, 'test.txt');
+        expect(await fs.pathExists(destFile)).toBe(true);
+        expect(await fs.readFile(destFile, 'utf8')).toBe('content');
+      });
+
+      it('should copy multiple files', async () => {
+        await createTestFile(sourceDir, 'file1.txt', 'content1');
+        await createTestFile(sourceDir, 'file2.md', 'content2');
+        await createTestFile(sourceDir, 'file3.json', '{}');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'file1.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'file2.md'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'file3.json'))).toBe(true);
+      });
+
+      it('should copy nested directory structure', async () => {
+        await createTestFile(sourceDir, 'root.txt', 'root');
+        await createTestFile(sourceDir, 'level1/file.txt', 'level1');
+        await createTestFile(sourceDir, 'level1/level2/deep.txt', 'deep');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'root.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'level1', 'file.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'level1', 'level2', 'deep.txt'))).toBe(true);
+      });
+
+      it('should create destination directory if it does not exist', async () => {
+        const newDest = path.join(tmpDir, 'new-dest');
+        await createTestFile(sourceDir, 'test.txt', 'content');
+
+        await fileOps.copyDirectory(sourceDir, newDest);
+
+        expect(await fs.pathExists(newDest)).toBe(true);
+        expect(await fs.pathExists(path.join(newDest, 'test.txt'))).toBe(true);
+      });
+    });
+
+    describe('overwrite behavior', () => {
+      it('should overwrite existing files by default', async () => {
+        await createTestFile(sourceDir, 'file.txt', 'new content');
+        await createTestFile(destDir, 'file.txt', 'old content');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const content = await fs.readFile(path.join(destDir, 'file.txt'), 'utf8');
+        expect(content).toBe('new content');
+      });
+
+      it('should preserve file content when overwriting', async () => {
+        await createTestFile(sourceDir, 'data.json', '{"new": true}');
+        await createTestFile(destDir, 'data.json', '{"old": true}');
+        await createTestFile(destDir, 'keep.txt', 'preserve this');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.readFile(path.join(destDir, 'data.json'), 'utf8')).toBe('{"new": true}');
+        // Files not in source should be preserved
+        expect(await fs.pathExists(path.join(destDir, 'keep.txt'))).toBe(true);
+      });
+    });
+
+    describe('filtering with shouldIgnore', () => {
+      it('should filter out .git directories', async () => {
+        await createTestFile(sourceDir, 'file.txt', 'content');
+        await createTestFile(sourceDir, '.git/config', 'git config');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'file.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, '.git'))).toBe(false);
+      });
+
+      it('should filter out node_modules directories', async () => {
+        await createTestFile(sourceDir, 'package.json', '{}');
+        await createTestFile(sourceDir, 'node_modules/lib/code.js', 'code');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'package.json'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'node_modules'))).toBe(false);
+      });
+
+      it('should filter out *.swp and *.tmp files', async () => {
+        await createTestFile(sourceDir, 'document.txt', 'content');
+        await createTestFile(sourceDir, 'document.txt.swp', 'vim swap');
+        await createTestFile(sourceDir, 'temp.tmp', 'temporary');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'document.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'document.txt.swp'))).toBe(false);
+        expect(await fs.pathExists(path.join(destDir, 'temp.tmp'))).toBe(false);
+      });
+
+      it('should filter out .DS_Store files', async () => {
+        await createTestFile(sourceDir, 'file.txt', 'content');
+        await createTestFile(sourceDir, '.DS_Store', 'mac metadata');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'file.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, '.DS_Store'))).toBe(false);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should handle empty source directory', async () => {
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const files = await fs.readdir(destDir);
+        expect(files).toHaveLength(0);
+      });
+
+      it('should handle Unicode filenames', async () => {
+        await createTestFile(sourceDir, '测试.txt', 'chinese');
+        await createTestFile(sourceDir, 'файл.json', 'russian');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, '测试.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'файл.json'))).toBe(true);
+      });
+
+      it('should handle filenames with special characters', async () => {
+        await createTestFile(sourceDir, 'file with spaces.txt', 'content');
+        await createTestFile(sourceDir, 'special-chars!@#.md', 'content');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'file with spaces.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'special-chars!@#.md'))).toBe(true);
+      });
+
+      it('should handle very deep directory nesting', async () => {
+        const deepPath = Array.from({ length: 10 }, (_, i) => `level${i}`).join('/');
+        await createTestFile(sourceDir, `${deepPath}/deep.txt`, 'very deep');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, ...deepPath.split('/'), 'deep.txt'))).toBe(true);
+      });
+
+      it('should preserve file permissions', async () => {
+        const execFile = path.join(sourceDir, 'script.sh');
+        await fs.writeFile(execFile, '#!/bin/bash\necho "test"');
+        await fs.chmod(execFile, 0o755); // Make executable
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const destFile = path.join(destDir, 'script.sh');
+        const stats = await fs.stat(destFile);
+        // Check if file is executable (user execute bit)
+        expect((stats.mode & 0o100) !== 0).toBe(true);
+      });
+
+      it('should handle large number of files', async () => {
+        // Create 50 files
+        const promises = Array.from({ length: 50 }, (_, i) => createTestFile(sourceDir, `file${i}.txt`, `content ${i}`));
+        await Promise.all(promises);
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const destFiles = await fs.readdir(destDir);
+        expect(destFiles).toHaveLength(50);
+      });
+    });
+
+    describe('content integrity', () => {
+      it('should preserve file content exactly', async () => {
+        const content = 'Line 1\nLine 2\nLine 3\n';
+        await createTestFile(sourceDir, 'file.txt', content);
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const copiedContent = await fs.readFile(path.join(destDir, 'file.txt'), 'utf8');
+        expect(copiedContent).toBe(content);
+      });
+
+      it('should preserve binary file content', async () => {
+        const buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        await fs.writeFile(path.join(sourceDir, 'binary.dat'), buffer);
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const copiedBuffer = await fs.readFile(path.join(destDir, 'binary.dat'));
+        expect(copiedBuffer).toEqual(buffer);
+      });
+
+      it('should preserve UTF-8 content', async () => {
+        const utf8Content = 'Hello 世界 🌍';
+        await createTestFile(sourceDir, 'utf8.txt', utf8Content);
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const copied = await fs.readFile(path.join(destDir, 'utf8.txt'), 'utf8');
+        expect(copied).toBe(utf8Content);
+      });
+
+      it('should preserve empty files', async () => {
+        await createTestFile(sourceDir, 'empty.txt', '');
+
+        await fileOps.copyDirectory(sourceDir, destDir);
+
+        const content = await fs.readFile(path.join(destDir, 'empty.txt'), 'utf8');
+        expect(content).toBe('');
+      });
+    });
+  });
+});
--- a/test/unit/file-ops/file-hash.test.js
+++ b/test/unit/file-ops/file-hash.test.js
@ -0,0 +1,211 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FileOps } from '../../../tools/cli/lib/file-ops.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+
+describe('FileOps', () => {
+  describe('getFileHash()', () => {
+    const fileOps = new FileOps();
+    let tmpDir;
+
+    beforeEach(async () => {
+      tmpDir = await createTempDir();
+    });
+
+    afterEach(async () => {
+      await cleanupTempDir(tmpDir);
+    });
+
+    describe('basic hashing', () => {
+      it('should return SHA256 hash for a simple file', async () => {
+        const filePath = await createTestFile(tmpDir, 'test.txt', 'hello');
+        const hash = await fileOps.getFileHash(filePath);
+
+        // SHA256 of 'hello' is known
+        expect(hash).toBe('2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824');
+        expect(hash).toHaveLength(64); // SHA256 is 64 hex characters
+      });
+
+      it('should return consistent hash for same content', async () => {
+        const content = 'test content for hashing';
+        const file1 = await createTestFile(tmpDir, 'file1.txt', content);
+        const file2 = await createTestFile(tmpDir, 'file2.txt', content);
+
+        const hash1 = await fileOps.getFileHash(file1);
+        const hash2 = await fileOps.getFileHash(file2);
+
+        expect(hash1).toBe(hash2);
+      });
+
+      it('should return different hash for different content', async () => {
+        const file1 = await createTestFile(tmpDir, 'file1.txt', 'content A');
+        const file2 = await createTestFile(tmpDir, 'file2.txt', 'content B');
+
+        const hash1 = await fileOps.getFileHash(file1);
+        const hash2 = await fileOps.getFileHash(file2);
+
+        expect(hash1).not.toBe(hash2);
+      });
+    });
+
+    describe('file size handling', () => {
+      it('should handle empty file', async () => {
+        const filePath = await createTestFile(tmpDir, 'empty.txt', '');
+        const hash = await fileOps.getFileHash(filePath);
+
+        // SHA256 of empty string
+        expect(hash).toBe('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');
+      });
+
+      it('should handle small file (<4KB)', async () => {
+        const content = 'a'.repeat(1000); // 1KB
+        const filePath = await createTestFile(tmpDir, 'small.txt', content);
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      });
+
+      it('should handle medium file (~1MB)', async () => {
+        const content = 'x'.repeat(1024 * 1024); // 1MB
+        const filePath = await createTestFile(tmpDir, 'medium.txt', content);
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      });
+
+      it('should handle large file (~10MB) via streaming', async () => {
+        // Create a 10MB file
+        const chunkSize = 1024 * 1024; // 1MB chunks
+        const chunks = Array.from({ length: 10 }, () => 'y'.repeat(chunkSize));
+        const content = chunks.join('');
+
+        const filePath = await createTestFile(tmpDir, 'large.txt', content);
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      }, 15_000); // 15 second timeout for large file
+    });
+
+    describe('content type handling', () => {
+      it('should handle binary content', async () => {
+        // Create a buffer with binary data
+        const buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        const filePath = await createTestFile(tmpDir, 'binary.dat', buffer.toString('binary'));
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      });
+
+      it('should handle UTF-8 content correctly', async () => {
+        const content = 'Hello 世界 🌍';
+        const filePath = await createTestFile(tmpDir, 'utf8.txt', content);
+        const hash = await fileOps.getFileHash(filePath);
+
+        // Hash should be consistent for UTF-8 content
+        const hash2 = await fileOps.getFileHash(filePath);
+        expect(hash).toBe(hash2);
+        expect(hash).toHaveLength(64);
+      });
+
+      it('should handle newline characters', async () => {
+        const contentLF = 'line1\nline2\nline3';
+        const contentCRLF = 'line1\r\nline2\r\nline3';
+
+        const fileLF = await createTestFile(tmpDir, 'lf.txt', contentLF);
+        const fileCRLF = await createTestFile(tmpDir, 'crlf.txt', contentCRLF);
+
+        const hashLF = await fileOps.getFileHash(fileLF);
+        const hashCRLF = await fileOps.getFileHash(fileCRLF);
+
+        // Different line endings should produce different hashes
+        expect(hashLF).not.toBe(hashCRLF);
+      });
+
+      it('should handle JSON content', async () => {
+        const json = JSON.stringify({ key: 'value', nested: { array: [1, 2, 3] } }, null, 2);
+        const filePath = await createTestFile(tmpDir, 'data.json', json);
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should handle file with special characters in name', async () => {
+        const filePath = await createTestFile(tmpDir, 'file with spaces & special-chars.txt', 'content');
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+      });
+
+      it('should handle concurrent hash calculations', async () => {
+        const files = await Promise.all([
+          createTestFile(tmpDir, 'file1.txt', 'content 1'),
+          createTestFile(tmpDir, 'file2.txt', 'content 2'),
+          createTestFile(tmpDir, 'file3.txt', 'content 3'),
+        ]);
+
+        // Calculate hashes concurrently
+        const hashes = await Promise.all(files.map((file) => fileOps.getFileHash(file)));
+
+        // All hashes should be valid
+        expect(hashes).toHaveLength(3);
+        for (const hash of hashes) {
+          expect(hash).toMatch(/^[a-f0-9]{64}$/);
+        }
+
+        // Hashes should be different
+        expect(hashes[0]).not.toBe(hashes[1]);
+        expect(hashes[1]).not.toBe(hashes[2]);
+        expect(hashes[0]).not.toBe(hashes[2]);
+      });
+
+      it('should handle file with only whitespace', async () => {
+        const filePath = await createTestFile(tmpDir, 'whitespace.txt', '   ');
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+        // Should be different from empty file
+        expect(hash).not.toBe('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');
+      });
+
+      it('should handle very long single line', async () => {
+        const longLine = 'x'.repeat(100_000); // 100KB single line
+        const filePath = await createTestFile(tmpDir, 'longline.txt', longLine);
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+      });
+    });
+
+    describe('error handling', () => {
+      it('should reject for non-existent file', async () => {
+        const nonExistentPath = `${tmpDir}/does-not-exist.txt`;
+
+        await expect(fileOps.getFileHash(nonExistentPath)).rejects.toThrow();
+      });
+
+      it('should reject for directory instead of file', async () => {
+        await expect(fileOps.getFileHash(tmpDir)).rejects.toThrow();
+      });
+    });
+
+    describe('streaming behavior', () => {
+      it('should use streaming for efficiency (test implementation detail)', async () => {
+        // This test verifies that the implementation uses streams
+        // by checking that large files can be processed without loading entirely into memory
+        const largeContent = 'z'.repeat(5 * 1024 * 1024); // 5MB
+        const filePath = await createTestFile(tmpDir, 'stream.txt', largeContent);
+
+        // If this completes without memory issues, streaming is working
+        const hash = await fileOps.getFileHash(filePath);
+
+        expect(hash).toHaveLength(64);
+        expect(hash).toMatch(/^[a-f0-9]{64}$/);
+      }, 10_000);
+    });
+  });
+});
--- a/test/unit/file-ops/get-file-list.test.js
+++ b/test/unit/file-ops/get-file-list.test.js
@ -0,0 +1,283 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FileOps } from '../../../tools/cli/lib/file-ops.js';
+import { createTempDir, cleanupTempDir, createTestFile, createTestDirs } from '../../helpers/temp-dir.js';
+import path from 'node:path';
+
+describe('FileOps', () => {
+  describe('getFileList()', () => {
+    const fileOps = new FileOps();
+    let tmpDir;
+
+    beforeEach(async () => {
+      tmpDir = await createTempDir();
+    });
+
+    afterEach(async () => {
+      await cleanupTempDir(tmpDir);
+    });
+
+    describe('basic functionality', () => {
+      it('should return empty array for empty directory', async () => {
+        const files = await fileOps.getFileList(tmpDir);
+        expect(files).toEqual([]);
+      });
+
+      it('should return single file in directory', async () => {
+        await createTestFile(tmpDir, 'test.txt', 'content');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('test.txt');
+      });
+
+      it('should return multiple files in directory', async () => {
+        await createTestFile(tmpDir, 'file1.txt', 'content1');
+        await createTestFile(tmpDir, 'file2.md', 'content2');
+        await createTestFile(tmpDir, 'file3.json', 'content3');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+        expect(files).toContain('file1.txt');
+        expect(files).toContain('file2.md');
+        expect(files).toContain('file3.json');
+      });
+    });
+
+    describe('recursive directory walking', () => {
+      it('should recursively find files in nested directories', async () => {
+        await createTestFile(tmpDir, 'root.txt', 'root');
+        await createTestFile(tmpDir, 'level1/file1.txt', 'level1');
+        await createTestFile(tmpDir, 'level1/level2/file2.txt', 'level2');
+        await createTestFile(tmpDir, 'level1/level2/level3/file3.txt', 'level3');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(4);
+        expect(files).toContain('root.txt');
+        expect(files).toContain(path.join('level1', 'file1.txt'));
+        expect(files).toContain(path.join('level1', 'level2', 'file2.txt'));
+        expect(files).toContain(path.join('level1', 'level2', 'level3', 'file3.txt'));
+      });
+
+      it('should handle multiple subdirectories at same level', async () => {
+        await createTestFile(tmpDir, 'dir1/file1.txt', 'content');
+        await createTestFile(tmpDir, 'dir2/file2.txt', 'content');
+        await createTestFile(tmpDir, 'dir3/file3.txt', 'content');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+        expect(files).toContain(path.join('dir1', 'file1.txt'));
+        expect(files).toContain(path.join('dir2', 'file2.txt'));
+        expect(files).toContain(path.join('dir3', 'file3.txt'));
+      });
+
+      it('should not include empty directories in results', async () => {
+        await createTestDirs(tmpDir, ['empty1', 'empty2', 'has-file']);
+        await createTestFile(tmpDir, 'has-file/file.txt', 'content');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe(path.join('has-file', 'file.txt'));
+      });
+    });
+
+    describe('ignore filtering', () => {
+      it('should ignore .git directories', async () => {
+        await createTestFile(tmpDir, 'normal.txt', 'content');
+        await createTestFile(tmpDir, '.git/config', 'git config');
+        await createTestFile(tmpDir, '.git/hooks/pre-commit', 'hook');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('normal.txt');
+      });
+
+      it('should ignore node_modules directories', async () => {
+        await createTestFile(tmpDir, 'package.json', '{}');
+        await createTestFile(tmpDir, 'node_modules/package/index.js', 'code');
+        await createTestFile(tmpDir, 'node_modules/package/lib/util.js', 'util');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('package.json');
+      });
+
+      it('should ignore .DS_Store files', async () => {
+        await createTestFile(tmpDir, 'file.txt', 'content');
+        await createTestFile(tmpDir, '.DS_Store', 'mac metadata');
+        await createTestFile(tmpDir, 'subdir/.DS_Store', 'mac metadata');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('file.txt');
+      });
+
+      it('should ignore *.swp and *.tmp files', async () => {
+        await createTestFile(tmpDir, 'document.txt', 'content');
+        await createTestFile(tmpDir, 'document.txt.swp', 'vim swap');
+        await createTestFile(tmpDir, 'temp.tmp', 'temporary');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe('document.txt');
+      });
+
+      it('should ignore multiple ignored patterns together', async () => {
+        await createTestFile(tmpDir, 'src/index.js', 'source code');
+        await createTestFile(tmpDir, 'node_modules/lib/code.js', 'dependency');
+        await createTestFile(tmpDir, '.git/config', 'git config');
+        await createTestFile(tmpDir, '.DS_Store', 'mac file');
+        await createTestFile(tmpDir, 'file.swp', 'swap file');
+        await createTestFile(tmpDir, '.idea/workspace.xml', 'ide');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe(path.join('src', 'index.js'));
+      });
+    });
+
+    describe('relative path handling', () => {
+      it('should return paths relative to base directory', async () => {
+        await createTestFile(tmpDir, 'a/b/c/deep.txt', 'deep');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files[0]).toBe(path.join('a', 'b', 'c', 'deep.txt'));
+        expect(path.isAbsolute(files[0])).toBe(false);
+      });
+
+      it('should handle subdirectory as base', async () => {
+        await createTestFile(tmpDir, 'root.txt', 'root');
+        await createTestFile(tmpDir, 'sub/file1.txt', 'sub1');
+        await createTestFile(tmpDir, 'sub/file2.txt', 'sub2');
+
+        const subDir = path.join(tmpDir, 'sub');
+        const files = await fileOps.getFileList(subDir);
+
+        expect(files).toHaveLength(2);
+        expect(files).toContain('file1.txt');
+        expect(files).toContain('file2.txt');
+        // Should not include root.txt
+        expect(files).not.toContain('root.txt');
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should handle directory with special characters', async () => {
+        await createTestFile(tmpDir, 'folder with spaces/file.txt', 'content');
+        await createTestFile(tmpDir, 'special-chars!@#/data.json', 'data');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(2);
+        expect(files).toContain(path.join('folder with spaces', 'file.txt'));
+        expect(files).toContain(path.join('special-chars!@#', 'data.json'));
+      });
+
+      it('should handle Unicode filenames', async () => {
+        await createTestFile(tmpDir, '文档/测试.txt', 'chinese');
+        await createTestFile(tmpDir, 'файл/данные.json', 'russian');
+        await createTestFile(tmpDir, 'ファイル/データ.yaml', 'japanese');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+        expect(files.some((f) => f.includes('测试.txt'))).toBe(true);
+        expect(files.some((f) => f.includes('данные.json'))).toBe(true);
+        expect(files.some((f) => f.includes('データ.yaml'))).toBe(true);
+      });
+
+      it('should return empty array for non-existent directory', async () => {
+        const nonExistent = path.join(tmpDir, 'does-not-exist');
+
+        const files = await fileOps.getFileList(nonExistent);
+
+        expect(files).toEqual([]);
+      });
+
+      it('should handle very deep directory nesting', async () => {
+        // Create a deeply nested structure (10 levels)
+        const deepPath = Array.from({ length: 10 }, (_, i) => `level${i}`).join('/');
+        await createTestFile(tmpDir, `${deepPath}/deep.txt`, 'very deep');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(1);
+        expect(files[0]).toBe(path.join(...deepPath.split('/'), 'deep.txt'));
+      });
+
+      it('should handle directory with many files', async () => {
+        // Create 100 files
+        const promises = Array.from({ length: 100 }, (_, i) => createTestFile(tmpDir, `file${i}.txt`, `content ${i}`));
+        await Promise.all(promises);
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(100);
+        expect(files.every((f) => f.startsWith('file') && f.endsWith('.txt'))).toBe(true);
+      });
+
+      it('should handle mixed ignored and non-ignored files', async () => {
+        await createTestFile(tmpDir, 'src/main.js', 'code');
+        await createTestFile(tmpDir, 'src/main.js.swp', 'swap');
+        await createTestFile(tmpDir, 'lib/utils.js', 'utils');
+        await createTestFile(tmpDir, 'node_modules/dep/index.js', 'dep');
+        await createTestFile(tmpDir, 'test/test.js', 'test');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+        expect(files).toContain(path.join('src', 'main.js'));
+        expect(files).toContain(path.join('lib', 'utils.js'));
+        expect(files).toContain(path.join('test', 'test.js'));
+      });
+    });
+
+    describe('file types', () => {
+      it('should include files with no extension', async () => {
+        await createTestFile(tmpDir, 'README', 'readme content');
+        await createTestFile(tmpDir, 'LICENSE', 'license text');
+        await createTestFile(tmpDir, 'Makefile', 'make commands');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+        expect(files).toContain('README');
+        expect(files).toContain('LICENSE');
+        expect(files).toContain('Makefile');
+      });
+
+      it('should include dotfiles (except ignored ones)', async () => {
+        await createTestFile(tmpDir, '.gitignore', 'ignore patterns');
+        await createTestFile(tmpDir, '.env', 'environment');
+        await createTestFile(tmpDir, '.eslintrc', 'eslint config');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+        expect(files).toContain('.gitignore');
+        expect(files).toContain('.env');
+        expect(files).toContain('.eslintrc');
+      });
+
+      it('should include files with multiple extensions', async () => {
+        await createTestFile(tmpDir, 'archive.tar.gz', 'archive');
+        await createTestFile(tmpDir, 'backup.sql.bak', 'backup');
+        await createTestFile(tmpDir, 'config.yaml.sample', 'sample config');
+
+        const files = await fileOps.getFileList(tmpDir);
+
+        expect(files).toHaveLength(3);
+      });
+    });
+  });
+});
--- a/test/unit/file-ops/should-ignore.test.js
+++ b/test/unit/file-ops/should-ignore.test.js
@ -0,0 +1,177 @@
+import { describe, it, expect } from 'vitest';
+import { FileOps } from '../../../tools/cli/lib/file-ops.js';
+
+describe('FileOps', () => {
+  describe('shouldIgnore()', () => {
+    const fileOps = new FileOps();
+
+    describe('exact matches', () => {
+      it('should ignore .git directory', () => {
+        expect(fileOps.shouldIgnore('.git')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/.git')).toBe(true);
+        // Note: basename of '/project/.git/hooks' is 'hooks', not '.git'
+        expect(fileOps.shouldIgnore('/project/.git/hooks')).toBe(false);
+      });
+
+      it('should ignore .DS_Store files', () => {
+        expect(fileOps.shouldIgnore('.DS_Store')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/.DS_Store')).toBe(true);
+      });
+
+      it('should ignore node_modules directory', () => {
+        expect(fileOps.shouldIgnore('node_modules')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/node_modules')).toBe(true);
+        // Note: basename of '/project/node_modules/package' is 'package', not 'node_modules'
+        expect(fileOps.shouldIgnore('/project/node_modules/package')).toBe(false);
+      });
+
+      it('should ignore .idea directory', () => {
+        expect(fileOps.shouldIgnore('.idea')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/.idea')).toBe(true);
+      });
+
+      it('should ignore .vscode directory', () => {
+        expect(fileOps.shouldIgnore('.vscode')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/.vscode')).toBe(true);
+      });
+
+      it('should ignore __pycache__ directory', () => {
+        expect(fileOps.shouldIgnore('__pycache__')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/__pycache__')).toBe(true);
+      });
+    });
+
+    describe('glob pattern matches', () => {
+      it('should ignore *.swp files (Vim swap files)', () => {
+        expect(fileOps.shouldIgnore('file.swp')).toBe(true);
+        expect(fileOps.shouldIgnore('.config.yaml.swp')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/document.txt.swp')).toBe(true);
+      });
+
+      it('should ignore *.tmp files (temporary files)', () => {
+        expect(fileOps.shouldIgnore('file.tmp')).toBe(true);
+        expect(fileOps.shouldIgnore('temp_data.tmp')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/cache.tmp')).toBe(true);
+      });
+
+      it('should ignore *.pyc files (Python compiled)', () => {
+        expect(fileOps.shouldIgnore('module.pyc')).toBe(true);
+        expect(fileOps.shouldIgnore('__init__.pyc')).toBe(true);
+        expect(fileOps.shouldIgnore('/path/to/script.pyc')).toBe(true);
+      });
+    });
+
+    describe('files that should NOT be ignored', () => {
+      it('should not ignore normal files', () => {
+        expect(fileOps.shouldIgnore('README.md')).toBe(false);
+        expect(fileOps.shouldIgnore('package.json')).toBe(false);
+        expect(fileOps.shouldIgnore('index.js')).toBe(false);
+      });
+
+      it('should not ignore .gitignore itself', () => {
+        expect(fileOps.shouldIgnore('.gitignore')).toBe(false);
+        expect(fileOps.shouldIgnore('/path/to/.gitignore')).toBe(false);
+      });
+
+      it('should not ignore files with similar but different names', () => {
+        expect(fileOps.shouldIgnore('git-file.txt')).toBe(false);
+        expect(fileOps.shouldIgnore('node_modules.backup')).toBe(false);
+        expect(fileOps.shouldIgnore('swap-file.txt')).toBe(false);
+      });
+
+      it('should not ignore files with ignored patterns in parent directory', () => {
+        // The pattern matches basename, not full path
+        expect(fileOps.shouldIgnore('/project/src/utils.js')).toBe(false);
+        expect(fileOps.shouldIgnore('/code/main.py')).toBe(false);
+      });
+
+      it('should not ignore directories with dot prefix (except specific ones)', () => {
+        expect(fileOps.shouldIgnore('.github')).toBe(false);
+        expect(fileOps.shouldIgnore('.husky')).toBe(false);
+        expect(fileOps.shouldIgnore('.npmrc')).toBe(false);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should handle empty string', () => {
+        expect(fileOps.shouldIgnore('')).toBe(false);
+      });
+
+      it('should handle paths with multiple segments', () => {
+        // basename of '/very/deep/path/to/node_modules/package' is 'package'
+        expect(fileOps.shouldIgnore('/very/deep/path/to/node_modules/package')).toBe(false);
+        expect(fileOps.shouldIgnore('/very/deep/path/to/file.swp')).toBe(true);
+        expect(fileOps.shouldIgnore('/very/deep/path/to/normal.js')).toBe(false);
+        // But the directory itself would be ignored
+        expect(fileOps.shouldIgnore('/very/deep/path/to/node_modules')).toBe(true);
+      });
+
+      it('should handle Windows-style paths', () => {
+        // Note: path.basename() on Unix doesn't recognize backslashes
+        // On Unix: basename('C:\\project\\file.tmp') = 'C:\\project\\file.tmp'
+        // So we test cross-platform path handling
+        expect(fileOps.shouldIgnore(String.raw`C:\project\file.tmp`)).toBe(true); // .tmp matches
+        expect(fileOps.shouldIgnore(String.raw`test\file.swp`)).toBe(true); // .swp matches
+        // These won't be ignored because they don't match the patterns on Unix
+        expect(fileOps.shouldIgnore(String.raw`C:\project\node_modules\pkg`)).toBe(false);
+        expect(fileOps.shouldIgnore(String.raw`C:\project\src\main.js`)).toBe(false);
+      });
+
+      it('should handle relative paths', () => {
+        // basename of './node_modules/package' is 'package'
+        expect(fileOps.shouldIgnore('./node_modules/package')).toBe(false);
+        // basename of '../.git/hooks' is 'hooks'
+        expect(fileOps.shouldIgnore('../.git/hooks')).toBe(false);
+        expect(fileOps.shouldIgnore('./src/index.js')).toBe(false);
+        // But the directories themselves would be ignored
+        expect(fileOps.shouldIgnore('./node_modules')).toBe(true);
+        expect(fileOps.shouldIgnore('../.git')).toBe(true);
+      });
+
+      it('should handle files with multiple extensions', () => {
+        expect(fileOps.shouldIgnore('file.tar.tmp')).toBe(true);
+        expect(fileOps.shouldIgnore('backup.sql.swp')).toBe(true);
+        expect(fileOps.shouldIgnore('data.json.gz')).toBe(false);
+      });
+
+      it('should be case-sensitive for exact matches', () => {
+        expect(fileOps.shouldIgnore('Node_Modules')).toBe(false);
+        expect(fileOps.shouldIgnore('NODE_MODULES')).toBe(false);
+        expect(fileOps.shouldIgnore('node_modules')).toBe(true);
+      });
+
+      it('should handle files starting with ignored patterns', () => {
+        expect(fileOps.shouldIgnore('.git-credentials')).toBe(false);
+        expect(fileOps.shouldIgnore('.gitattributes')).toBe(false);
+        expect(fileOps.shouldIgnore('.git')).toBe(true);
+      });
+
+      it('should handle Unicode filenames', () => {
+        expect(fileOps.shouldIgnore('文档.swp')).toBe(true);
+        expect(fileOps.shouldIgnore('файл.tmp')).toBe(true);
+        expect(fileOps.shouldIgnore('ドキュメント.txt')).toBe(false);
+      });
+    });
+
+    describe('pattern matching behavior', () => {
+      it('should match patterns based on basename only', () => {
+        // shouldIgnore uses path.basename(), so only the last segment matters
+        expect(fileOps.shouldIgnore('/home/user/.git/config')).toBe(false); // basename is 'config'
+        expect(fileOps.shouldIgnore('/home/user/project/node_modules')).toBe(true); // basename is 'node_modules'
+      });
+
+      it('should handle trailing slashes', () => {
+        // path.basename() returns the directory name, not empty string for trailing slash
+        expect(fileOps.shouldIgnore('node_modules/')).toBe(true);
+        expect(fileOps.shouldIgnore('.git/')).toBe(true);
+      });
+
+      it('should treat patterns as partial regex matches', () => {
+        // The *.swp pattern becomes /.*\.swp/ regex
+        expect(fileOps.shouldIgnore('test.swp')).toBe(true);
+        expect(fileOps.shouldIgnore('swp')).toBe(false); // doesn't match .*\.swp
+        expect(fileOps.shouldIgnore('.swp')).toBe(true); // matches .*\.swp (. before swp)
+      });
+    });
+  });
+});
--- a/test/unit/file-ops/sync-directory.test.js
+++ b/test/unit/file-ops/sync-directory.test.js
@ -0,0 +1,316 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FileOps } from '../../../tools/cli/lib/file-ops.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+describe('FileOps', () => {
+  describe('syncDirectory()', () => {
+    const fileOps = new FileOps();
+    let tmpDir;
+    let sourceDir;
+    let destDir;
+
+    beforeEach(async () => {
+      tmpDir = await createTempDir();
+      sourceDir = path.join(tmpDir, 'source');
+      destDir = path.join(tmpDir, 'dest');
+      await fs.ensureDir(sourceDir);
+      await fs.ensureDir(destDir);
+    });
+
+    afterEach(async () => {
+      await cleanupTempDir(tmpDir);
+    });
+
+    describe('hash-based selective update', () => {
+      it('should update file when hashes are identical (safe update)', async () => {
+        const content = 'identical content';
+        await createTestFile(sourceDir, 'file.txt', content);
+        await createTestFile(destDir, 'file.txt', content);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // File should be updated (copied over) since hashes match
+        const destContent = await fs.readFile(path.join(destDir, 'file.txt'), 'utf8');
+        expect(destContent).toBe(content);
+      });
+
+      it('should preserve modified file when dest is newer', async () => {
+        await createTestFile(sourceDir, 'file.txt', 'source content');
+        await createTestFile(destDir, 'file.txt', 'modified by user');
+
+        // Make dest file newer
+        const destFile = path.join(destDir, 'file.txt');
+        const futureTime = new Date(Date.now() + 10_000);
+        await fs.utimes(destFile, futureTime, futureTime);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // User modification should be preserved
+        const destContent = await fs.readFile(destFile, 'utf8');
+        expect(destContent).toBe('modified by user');
+      });
+
+      it('should update file when source is newer than modified dest', async () => {
+        // Create both files first
+        await createTestFile(sourceDir, 'file.txt', 'new source content');
+        await createTestFile(destDir, 'file.txt', 'old modified content');
+
+        // Make dest older and source newer with explicit times
+        const destFile = path.join(destDir, 'file.txt');
+        const sourceFile = path.join(sourceDir, 'file.txt');
+
+        const pastTime = new Date(Date.now() - 10_000);
+        const futureTime = new Date(Date.now() + 10_000);
+
+        await fs.utimes(destFile, pastTime, pastTime);
+        await fs.utimes(sourceFile, futureTime, futureTime);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // Should update to source content since source is newer
+        const destContent = await fs.readFile(destFile, 'utf8');
+        expect(destContent).toBe('new source content');
+      });
+    });
+
+    describe('new file handling', () => {
+      it('should copy new files from source', async () => {
+        await createTestFile(sourceDir, 'new-file.txt', 'new content');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'new-file.txt'))).toBe(true);
+        expect(await fs.readFile(path.join(destDir, 'new-file.txt'), 'utf8')).toBe('new content');
+      });
+
+      it('should copy multiple new files', async () => {
+        await createTestFile(sourceDir, 'file1.txt', 'content1');
+        await createTestFile(sourceDir, 'file2.md', 'content2');
+        await createTestFile(sourceDir, 'file3.json', 'content3');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'file1.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'file2.md'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'file3.json'))).toBe(true);
+      });
+
+      it('should create nested directories for new files', async () => {
+        await createTestFile(sourceDir, 'level1/level2/deep.txt', 'deep content');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'level1', 'level2', 'deep.txt'))).toBe(true);
+      });
+    });
+
+    describe('orphaned file removal', () => {
+      it('should remove files that no longer exist in source', async () => {
+        await createTestFile(sourceDir, 'keep.txt', 'keep this');
+        await createTestFile(destDir, 'keep.txt', 'keep this');
+        await createTestFile(destDir, 'remove.txt', 'delete this');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'keep.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'remove.txt'))).toBe(false);
+      });
+
+      it('should remove multiple orphaned files', async () => {
+        await createTestFile(sourceDir, 'current.txt', 'current');
+        await createTestFile(destDir, 'current.txt', 'current');
+        await createTestFile(destDir, 'old1.txt', 'orphan 1');
+        await createTestFile(destDir, 'old2.txt', 'orphan 2');
+        await createTestFile(destDir, 'old3.txt', 'orphan 3');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'current.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'old1.txt'))).toBe(false);
+        expect(await fs.pathExists(path.join(destDir, 'old2.txt'))).toBe(false);
+        expect(await fs.pathExists(path.join(destDir, 'old3.txt'))).toBe(false);
+      });
+
+      it('should remove orphaned directories', async () => {
+        await createTestFile(sourceDir, 'keep/file.txt', 'keep');
+        await createTestFile(destDir, 'keep/file.txt', 'keep');
+        await createTestFile(destDir, 'remove/orphan.txt', 'orphan');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'keep'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'remove', 'orphan.txt'))).toBe(false);
+      });
+    });
+
+    describe('complex scenarios', () => {
+      it('should handle mixed operations in single sync', async () => {
+        const now = Date.now();
+        const pastTime = now - 100_000; // 100 seconds ago
+        const futureTime = now + 100_000; // 100 seconds from now
+
+        // Identical file (update)
+        await createTestFile(sourceDir, 'identical.txt', 'same');
+        await createTestFile(destDir, 'identical.txt', 'same');
+
+        // Modified file with newer dest (preserve)
+        await createTestFile(sourceDir, 'modified.txt', 'original');
+        await createTestFile(destDir, 'modified.txt', 'user modified');
+        const modifiedFile = path.join(destDir, 'modified.txt');
+        await fs.utimes(modifiedFile, futureTime, futureTime);
+
+        // New file (copy)
+        await createTestFile(sourceDir, 'new.txt', 'new content');
+
+        // Orphaned file (remove)
+        await createTestFile(destDir, 'orphan.txt', 'delete me');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // Verify operations
+        expect(await fs.pathExists(path.join(destDir, 'identical.txt'))).toBe(true);
+
+        expect(await fs.readFile(modifiedFile, 'utf8')).toBe('user modified');
+
+        expect(await fs.pathExists(path.join(destDir, 'new.txt'))).toBe(true);
+
+        expect(await fs.pathExists(path.join(destDir, 'orphan.txt'))).toBe(false);
+      });
+
+      it('should handle nested directory changes', async () => {
+        // Create nested structure in source
+        await createTestFile(sourceDir, 'level1/keep.txt', 'keep');
+        await createTestFile(sourceDir, 'level1/level2/deep.txt', 'deep');
+
+        // Create different nested structure in dest
+        await createTestFile(destDir, 'level1/keep.txt', 'keep');
+        await createTestFile(destDir, 'level1/remove.txt', 'orphan');
+        await createTestFile(destDir, 'old-level/file.txt', 'old');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'level1', 'keep.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'level1', 'level2', 'deep.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'level1', 'remove.txt'))).toBe(false);
+        expect(await fs.pathExists(path.join(destDir, 'old-level', 'file.txt'))).toBe(false);
+      });
+    });
+
+    describe('edge cases', () => {
+      it('should handle empty source directory', async () => {
+        await createTestFile(destDir, 'file.txt', 'content');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // All files should be removed
+        expect(await fs.pathExists(path.join(destDir, 'file.txt'))).toBe(false);
+      });
+
+      it('should handle empty destination directory', async () => {
+        await createTestFile(sourceDir, 'file.txt', 'content');
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.pathExists(path.join(destDir, 'file.txt'))).toBe(true);
+      });
+
+      it('should handle Unicode filenames', async () => {
+        await createTestFile(sourceDir, '测试.txt', 'chinese');
+        await createTestFile(destDir, '测试.txt', 'modified chinese');
+
+        // Make dest newer
+        await fs.utimes(path.join(destDir, '测试.txt'), Date.now() + 10_000, Date.now() + 10_000);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // Should preserve user modification
+        expect(await fs.readFile(path.join(destDir, '测试.txt'), 'utf8')).toBe('modified chinese');
+      });
+
+      it('should handle large number of files', async () => {
+        // Create 50 files in source
+        for (let i = 0; i < 50; i++) {
+          await createTestFile(sourceDir, `file${i}.txt`, `content ${i}`);
+        }
+
+        // Create 25 matching files and 25 orphaned files in dest
+        for (let i = 0; i < 25; i++) {
+          await createTestFile(destDir, `file${i}.txt`, `content ${i}`);
+          await createTestFile(destDir, `orphan${i}.txt`, `orphan ${i}`);
+        }
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // All 50 source files should exist
+        for (let i = 0; i < 50; i++) {
+          expect(await fs.pathExists(path.join(destDir, `file${i}.txt`))).toBe(true);
+        }
+
+        // All 25 orphaned files should be removed
+        for (let i = 0; i < 25; i++) {
+          expect(await fs.pathExists(path.join(destDir, `orphan${i}.txt`))).toBe(false);
+        }
+      });
+
+      it('should handle binary files correctly', async () => {
+        const buffer = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+        await fs.writeFile(path.join(sourceDir, 'binary.dat'), buffer);
+        await fs.writeFile(path.join(destDir, 'binary.dat'), buffer);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        const destBuffer = await fs.readFile(path.join(destDir, 'binary.dat'));
+        expect(destBuffer).toEqual(buffer);
+      });
+    });
+
+    describe('timestamp precision', () => {
+      it('should handle files with very close modification times', async () => {
+        await createTestFile(sourceDir, 'file.txt', 'source');
+        await createTestFile(destDir, 'file.txt', 'dest modified');
+
+        // Make dest just slightly newer (100ms)
+        const destFile = path.join(destDir, 'file.txt');
+        await fs.utimes(destFile, Date.now() + 100, Date.now() + 100);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // Should preserve user modification even with small time difference
+        expect(await fs.readFile(destFile, 'utf8')).toBe('dest modified');
+      });
+    });
+
+    describe('data integrity', () => {
+      it('should not corrupt files during sync', async () => {
+        const content = 'Important data\nLine 2\nLine 3\n';
+        await createTestFile(sourceDir, 'data.txt', content);
+
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        expect(await fs.readFile(path.join(destDir, 'data.txt'), 'utf8')).toBe(content);
+      });
+
+      it('should handle sync interruption gracefully', async () => {
+        // This test verifies that partial syncs don't leave inconsistent state
+        await createTestFile(sourceDir, 'file1.txt', 'content1');
+        await createTestFile(sourceDir, 'file2.txt', 'content2');
+
+        // First sync
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // Modify source
+        await createTestFile(sourceDir, 'file3.txt', 'content3');
+
+        // Second sync
+        await fileOps.syncDirectory(sourceDir, destDir);
+
+        // All files should be present and correct
+        expect(await fs.pathExists(path.join(destDir, 'file1.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'file2.txt'))).toBe(true);
+        expect(await fs.pathExists(path.join(destDir, 'file3.txt'))).toBe(true);
+      });
+    });
+  });
+});
--- a/test/unit/file-ops/utility-methods.test.js
+++ b/test/unit/file-ops/utility-methods.test.js
@ -0,0 +1,214 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { FileOps } from '../../../tools/cli/lib/file-ops.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+
+describe('FileOps', () => {
+  const fileOps = new FileOps();
+  let tmpDir;
+
+  beforeEach(async () => {
+    tmpDir = await createTempDir();
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tmpDir);
+  });
+
+  describe('ensureDir()', () => {
+    it('should create directory if it does not exist', async () => {
+      const newDir = path.join(tmpDir, 'new-directory');
+
+      await fileOps.ensureDir(newDir);
+
+      expect(await fs.pathExists(newDir)).toBe(true);
+    });
+
+    it('should not fail if directory already exists', async () => {
+      const existingDir = path.join(tmpDir, 'existing');
+      await fs.ensureDir(existingDir);
+
+      await expect(fileOps.ensureDir(existingDir)).resolves.not.toThrow();
+    });
+
+    it('should create nested directories', async () => {
+      const nestedDir = path.join(tmpDir, 'level1', 'level2', 'level3');
+
+      await fileOps.ensureDir(nestedDir);
+
+      expect(await fs.pathExists(nestedDir)).toBe(true);
+    });
+  });
+
+  describe('remove()', () => {
+    it('should remove a file', async () => {
+      const filePath = await createTestFile(tmpDir, 'test.txt', 'content');
+
+      await fileOps.remove(filePath);
+
+      expect(await fs.pathExists(filePath)).toBe(false);
+    });
+
+    it('should remove a directory', async () => {
+      const dirPath = path.join(tmpDir, 'test-dir');
+      await fs.ensureDir(dirPath);
+      await createTestFile(dirPath, 'file.txt', 'content');
+
+      await fileOps.remove(dirPath);
+
+      expect(await fs.pathExists(dirPath)).toBe(false);
+    });
+
+    it('should not fail if path does not exist', async () => {
+      const nonExistent = path.join(tmpDir, 'does-not-exist');
+
+      await expect(fileOps.remove(nonExistent)).resolves.not.toThrow();
+    });
+
+    it('should remove nested directories', async () => {
+      const nested = path.join(tmpDir, 'a', 'b', 'c');
+      await fs.ensureDir(nested);
+      await createTestFile(nested, 'file.txt', 'content');
+
+      await fileOps.remove(path.join(tmpDir, 'a'));
+
+      expect(await fs.pathExists(path.join(tmpDir, 'a'))).toBe(false);
+    });
+  });
+
+  describe('readFile()', () => {
+    it('should read file content', async () => {
+      const content = 'test content';
+      const filePath = await createTestFile(tmpDir, 'test.txt', content);
+
+      const result = await fileOps.readFile(filePath);
+
+      expect(result).toBe(content);
+    });
+
+    it('should read UTF-8 content', async () => {
+      const content = 'Hello 世界 🌍';
+      const filePath = await createTestFile(tmpDir, 'utf8.txt', content);
+
+      const result = await fileOps.readFile(filePath);
+
+      expect(result).toBe(content);
+    });
+
+    it('should read empty file', async () => {
+      const filePath = await createTestFile(tmpDir, 'empty.txt', '');
+
+      const result = await fileOps.readFile(filePath);
+
+      expect(result).toBe('');
+    });
+
+    it('should reject for non-existent file', async () => {
+      const nonExistent = path.join(tmpDir, 'does-not-exist.txt');
+
+      await expect(fileOps.readFile(nonExistent)).rejects.toThrow();
+    });
+  });
+
+  describe('writeFile()', () => {
+    it('should write file content', async () => {
+      const filePath = path.join(tmpDir, 'new-file.txt');
+      const content = 'test content';
+
+      await fileOps.writeFile(filePath, content);
+
+      expect(await fs.readFile(filePath, 'utf8')).toBe(content);
+    });
+
+    it('should create parent directories if they do not exist', async () => {
+      const filePath = path.join(tmpDir, 'level1', 'level2', 'file.txt');
+
+      await fileOps.writeFile(filePath, 'content');
+
+      expect(await fs.pathExists(filePath)).toBe(true);
+      expect(await fs.readFile(filePath, 'utf8')).toBe('content');
+    });
+
+    it('should overwrite existing file', async () => {
+      const filePath = await createTestFile(tmpDir, 'test.txt', 'old content');
+
+      await fileOps.writeFile(filePath, 'new content');
+
+      expect(await fs.readFile(filePath, 'utf8')).toBe('new content');
+    });
+
+    it('should handle UTF-8 content', async () => {
+      const content = '测试 Тест 🎉';
+      const filePath = path.join(tmpDir, 'unicode.txt');
+
+      await fileOps.writeFile(filePath, content);
+
+      expect(await fs.readFile(filePath, 'utf8')).toBe(content);
+    });
+  });
+
+  describe('exists()', () => {
+    it('should return true for existing file', async () => {
+      const filePath = await createTestFile(tmpDir, 'test.txt', 'content');
+
+      const result = await fileOps.exists(filePath);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return true for existing directory', async () => {
+      const dirPath = path.join(tmpDir, 'test-dir');
+      await fs.ensureDir(dirPath);
+
+      const result = await fileOps.exists(dirPath);
+
+      expect(result).toBe(true);
+    });
+
+    it('should return false for non-existent path', async () => {
+      const nonExistent = path.join(tmpDir, 'does-not-exist');
+
+      const result = await fileOps.exists(nonExistent);
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('stat()', () => {
+    it('should return stats for file', async () => {
+      const filePath = await createTestFile(tmpDir, 'test.txt', 'content');
+
+      const stats = await fileOps.stat(filePath);
+
+      expect(stats.isFile()).toBe(true);
+      expect(stats.isDirectory()).toBe(false);
+      expect(stats.size).toBeGreaterThan(0);
+    });
+
+    it('should return stats for directory', async () => {
+      const dirPath = path.join(tmpDir, 'test-dir');
+      await fs.ensureDir(dirPath);
+
+      const stats = await fileOps.stat(dirPath);
+
+      expect(stats.isDirectory()).toBe(true);
+      expect(stats.isFile()).toBe(false);
+    });
+
+    it('should reject for non-existent path', async () => {
+      const nonExistent = path.join(tmpDir, 'does-not-exist');
+
+      await expect(fileOps.stat(nonExistent)).rejects.toThrow();
+    });
+
+    it('should return modification time', async () => {
+      const filePath = await createTestFile(tmpDir, 'test.txt', 'content');
+
+      const stats = await fileOps.stat(filePath);
+
+      expect(stats.mtime).toBeInstanceOf(Date);
+      expect(stats.mtime.getTime()).toBeLessThanOrEqual(Date.now());
+    });
+  });
+});
--- a/test/unit/transformations/build-commands-xml.test.js
+++ b/test/unit/transformations/build-commands-xml.test.js
@ -0,0 +1,335 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { YamlXmlBuilder } from '../../../tools/cli/lib/yaml-xml-builder.js';
+
+describe('YamlXmlBuilder - buildCommandsXml()', () => {
+  let builder;
+
+  beforeEach(() => {
+    builder = new YamlXmlBuilder();
+  });
+
+  describe('menu injection', () => {
+    it('should always inject *menu item first', () => {
+      const xml = builder.buildCommandsXml([]);
+
+      expect(xml).toContain('<item cmd="*menu">[M] Redisplay Menu Options</item>');
+    });
+
+    it('should always inject *dismiss item last', () => {
+      const xml = builder.buildCommandsXml([]);
+
+      expect(xml).toContain('<item cmd="*dismiss">[D] Dismiss Agent</item>');
+      // Should be at the end before </menu>
+      expect(xml).toMatch(/\*dismiss.*<\/menu>/s);
+    });
+
+    it('should place user items between *menu and *dismiss', () => {
+      const menuItems = [{ trigger: 'help', description: 'Show help', action: 'show_help' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      const menuIndex = xml.indexOf('*menu');
+      const helpIndex = xml.indexOf('*help');
+      const dismissIndex = xml.indexOf('*dismiss');
+
+      expect(menuIndex).toBeLessThan(helpIndex);
+      expect(helpIndex).toBeLessThan(dismissIndex);
+    });
+  });
+
+  describe('legacy format items', () => {
+    it('should add * prefix to triggers', () => {
+      const menuItems = [{ trigger: 'help', description: 'Help', action: 'show_help' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('cmd="*help"');
+      expect(xml).not.toContain('cmd="help"'); // Should not have unprefixed version
+    });
+
+    it('should preserve * prefix if already present', () => {
+      const menuItems = [{ trigger: '*custom', description: 'Custom', action: 'custom_action' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('cmd="*custom"');
+      expect(xml).not.toContain('cmd="**custom"'); // Should not double-prefix
+    });
+
+    it('should include description as item content', () => {
+      const menuItems = [{ trigger: 'analyze', description: '[A] Analyze code', action: 'analyze' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('>[A] Analyze code</item>');
+    });
+
+    it('should escape XML special characters in description', () => {
+      const menuItems = [
+        {
+          trigger: 'test',
+          description: 'Test <brackets> & "quotes"',
+          action: 'test',
+        },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('&lt;brackets&gt; &amp; &quot;quotes&quot;');
+    });
+  });
+
+  describe('handler attributes', () => {
+    it('should include workflow attribute', () => {
+      const menuItems = [{ trigger: 'start', description: 'Start workflow', workflow: 'main-workflow' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('workflow="main-workflow"');
+    });
+
+    it('should include exec attribute', () => {
+      const menuItems = [{ trigger: 'run', description: 'Run task', exec: 'path/to/task.md' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('exec="path/to/task.md"');
+    });
+
+    it('should include action attribute', () => {
+      const menuItems = [{ trigger: 'help', description: 'Help', action: 'show_help' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('action="show_help"');
+    });
+
+    it('should include tmpl attribute', () => {
+      const menuItems = [{ trigger: 'form', description: 'Form', tmpl: 'templates/form.yaml' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('tmpl="templates/form.yaml"');
+    });
+
+    it('should include data attribute', () => {
+      const menuItems = [{ trigger: 'load', description: 'Load', data: 'data/config.json' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('data="data/config.json"');
+    });
+
+    it('should include validate-workflow attribute', () => {
+      const menuItems = [
+        {
+          trigger: 'validate',
+          description: 'Validate',
+          'validate-workflow': 'validation-flow',
+        },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('validate-workflow="validation-flow"');
+    });
+
+    it('should prioritize workflow-install over workflow', () => {
+      const menuItems = [
+        {
+          trigger: 'start',
+          description: 'Start',
+          workflow: 'original',
+          'workflow-install': 'installed-location',
+        },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('workflow="installed-location"');
+      expect(xml).not.toContain('workflow="original"');
+    });
+
+    it('should handle multiple attributes on same item', () => {
+      const menuItems = [
+        {
+          trigger: 'complex',
+          description: 'Complex command',
+          workflow: 'flow',
+          data: 'data.json',
+          action: 'custom',
+        },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('workflow="flow"');
+      expect(xml).toContain('data="data.json"');
+      expect(xml).toContain('action="custom"');
+    });
+  });
+
+  describe('IDE and web filtering', () => {
+    it('should include ide-only items for IDE installation', () => {
+      const menuItems = [
+        { trigger: 'local', description: 'Local only', action: 'local', 'ide-only': true },
+        { trigger: 'normal', description: 'Normal', action: 'normal' },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems, false);
+
+      expect(xml).toContain('*local');
+      expect(xml).toContain('*normal');
+    });
+
+    it('should skip ide-only items for web bundle', () => {
+      const menuItems = [
+        { trigger: 'local', description: 'Local only', action: 'local', 'ide-only': true },
+        { trigger: 'normal', description: 'Normal', action: 'normal' },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems, true);
+
+      expect(xml).not.toContain('*local');
+      expect(xml).toContain('*normal');
+    });
+
+    it('should include web-only items for web bundle', () => {
+      const menuItems = [
+        { trigger: 'web', description: 'Web only', action: 'web', 'web-only': true },
+        { trigger: 'normal', description: 'Normal', action: 'normal' },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems, true);
+
+      expect(xml).toContain('*web');
+      expect(xml).toContain('*normal');
+    });
+
+    it('should skip web-only items for IDE installation', () => {
+      const menuItems = [
+        { trigger: 'web', description: 'Web only', action: 'web', 'web-only': true },
+        { trigger: 'normal', description: 'Normal', action: 'normal' },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems, false);
+
+      expect(xml).not.toContain('*web');
+      expect(xml).toContain('*normal');
+    });
+  });
+
+  describe('multi format with nested handlers', () => {
+    it('should build multi format items with nested handlers', () => {
+      const menuItems = [
+        {
+          multi: '[TS] Technical Specification',
+          triggers: [
+            {
+              'tech-spec': [{ input: 'Create technical specification' }, { route: 'workflows/tech-spec.yaml' }],
+            },
+            {
+              TS: [{ input: 'Create technical specification' }, { route: 'workflows/tech-spec.yaml' }],
+            },
+          ],
+        },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('<item type="multi">');
+      expect(xml).toContain('[TS] Technical Specification');
+      expect(xml).toContain('<handler');
+      expect(xml).toContain('match="Create technical specification"');
+      expect(xml).toContain('</item>');
+    });
+
+    it('should escape XML in multi description', () => {
+      const menuItems = [
+        {
+          multi: '[A] Analyze <code>',
+          triggers: [
+            {
+              analyze: [{ input: 'Analyze', route: 'task.md' }],
+            },
+          ],
+        },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('&lt;code&gt;');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty menu items array', () => {
+      const xml = builder.buildCommandsXml([]);
+
+      expect(xml).toContain('<menu>');
+      expect(xml).toContain('</menu>');
+      expect(xml).toContain('*menu');
+      expect(xml).toContain('*dismiss');
+    });
+
+    it('should handle null menu items', () => {
+      const xml = builder.buildCommandsXml(null);
+
+      expect(xml).toContain('<menu>');
+      expect(xml).toContain('*menu');
+      expect(xml).toContain('*dismiss');
+    });
+
+    it('should handle undefined menu items', () => {
+      const xml = builder.buildCommandsXml();
+
+      expect(xml).toContain('<menu>');
+    });
+
+    it('should handle empty description', () => {
+      const menuItems = [{ trigger: 'test', description: '', action: 'test' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('cmd="*test"');
+      expect(xml).toContain('></item>'); // Empty content between tags
+    });
+
+    it('should handle missing trigger (edge case)', () => {
+      const menuItems = [{ description: 'No trigger', action: 'test' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      // Should handle gracefully - might skip or add * prefix to empty
+      expect(xml).toContain('<menu>');
+    });
+
+    it('should handle Unicode in descriptions', () => {
+      const menuItems = [{ trigger: 'test', description: '[测试] Test 日本語', action: 'test' }];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      expect(xml).toContain('测试');
+      expect(xml).toContain('日本語');
+    });
+  });
+
+  describe('multiple menu items', () => {
+    it('should process all menu items in order', () => {
+      const menuItems = [
+        { trigger: 'first', description: 'First', action: 'first' },
+        { trigger: 'second', description: 'Second', action: 'second' },
+        { trigger: 'third', description: 'Third', action: 'third' },
+      ];
+
+      const xml = builder.buildCommandsXml(menuItems);
+
+      const firstIndex = xml.indexOf('*first');
+      const secondIndex = xml.indexOf('*second');
+      const thirdIndex = xml.indexOf('*third');
+
+      expect(firstIndex).toBeLessThan(secondIndex);
+      expect(secondIndex).toBeLessThan(thirdIndex);
+    });
+  });
+});
--- a/test/unit/transformations/convert-to-xml.test.js
+++ b/test/unit/transformations/convert-to-xml.test.js
@ -0,0 +1,605 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { YamlXmlBuilder } from '../../../tools/cli/lib/yaml-xml-builder.js';
+
+describe('YamlXmlBuilder - convertToXml()', () => {
+  let builder;
+
+  beforeEach(() => {
+    builder = new YamlXmlBuilder();
+  });
+
+  describe('basic XML generation', () => {
+    it('should generate XML with agent tag and attributes', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: {
+            id: 'test-agent',
+            name: 'Test Agent',
+            title: 'Test Agent Title',
+            icon: '🔧',
+          },
+          persona: {
+            role: 'Test Role',
+            identity: 'Test Identity',
+            communication_style: 'Professional',
+            principles: ['Principle 1'],
+          },
+          menu: [{ trigger: 'help', description: 'Help', action: 'show_help' }],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<agent id="test-agent"');
+      expect(xml).toContain('name="Test Agent"');
+      expect(xml).toContain('title="Test Agent Title"');
+      expect(xml).toContain('icon="🔧"');
+      expect(xml).toContain('</agent>');
+    });
+
+    it('should include persona section', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Developer',
+            identity: 'Helpful assistant',
+            communication_style: 'Professional',
+            principles: ['Clear', 'Concise'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<persona>');
+      expect(xml).toContain('<role>Developer</role>');
+      expect(xml).toContain('<identity>Helpful assistant</identity>');
+      expect(xml).toContain('<communication_style>Professional</communication_style>');
+      expect(xml).toContain('<principles>Clear Concise</principles>');
+    });
+
+    it('should include memories section if present', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          memories: ['Memory 1', 'Memory 2'],
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<memories>');
+      expect(xml).toContain('<memory>Memory 1</memory>');
+      expect(xml).toContain('<memory>Memory 2</memory>');
+    });
+
+    it('should include prompts section if present', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          prompts: [{ id: 'p1', content: 'Prompt content' }],
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<prompts>');
+      expect(xml).toContain('<prompt id="p1">');
+      expect(xml).toContain('Prompt content');
+    });
+
+    it('should include menu section', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [
+            { trigger: 'help', description: 'Show help', action: 'show_help' },
+            { trigger: 'start', description: 'Start workflow', workflow: 'main' },
+          ],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<menu>');
+      expect(xml).toContain('</menu>');
+      // Menu always includes injected *menu item
+      expect(xml).toContain('*menu');
+    });
+  });
+
+  describe('XML escaping', () => {
+    it('should escape special characters in all fields', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: {
+            id: 'test',
+            name: 'Test',
+            title: 'Test Agent',
+            icon: '🔧',
+          },
+          persona: {
+            role: 'Role with <brackets>',
+            identity: 'Identity with & ampersand',
+            communication_style: 'Style with "quotes"',
+            principles: ["Principle with ' apostrophe"],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      // Metadata in attributes might not be escaped - focus on content
+      expect(xml).toContain('&lt;brackets&gt;');
+      expect(xml).toContain('&amp; ampersand');
+      expect(xml).toContain('&quot;quotes&quot;');
+      expect(xml).toContain('&apos; apostrophe');
+    });
+
+    it('should preserve Unicode characters', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: {
+            id: 'unicode',
+            name: '测试代理',
+            title: 'Тестовый агент',
+            icon: '🔧',
+          },
+          persona: {
+            role: '開発者',
+            identity: 'مساعد مفيد',
+            communication_style: 'Profesional',
+            principles: ['原则'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('测试代理');
+      expect(xml).toContain('Тестовый агент');
+      expect(xml).toContain('開発者');
+      expect(xml).toContain('مساعد مفيد');
+      expect(xml).toContain('原则');
+    });
+  });
+
+  describe('module detection', () => {
+    it('should handle module in buildMetadata', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        module: 'bmm',
+        skipActivation: true,
+      });
+
+      // Module is stored in metadata but may not be rendered as attribute
+      expect(xml).toContain('<agent');
+      expect(xml).toBeDefined();
+    });
+
+    it('should not include module attribute for core agents', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      // No module attribute for core
+      expect(xml).not.toContain('module=');
+    });
+  });
+
+  describe('output format variations', () => {
+    it('should generate installation format with YAML frontmatter', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test Agent', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        sourceFile: 'test-agent.yaml',
+        skipActivation: true,
+      });
+
+      // Installation format has YAML frontmatter
+      expect(xml).toMatch(/^---\n/);
+      expect(xml).toContain('name: "test agent"'); // Derived from filename
+      expect(xml).toContain('description: "Test Agent"');
+      expect(xml).toContain('---');
+    });
+
+    it('should generate web bundle format without frontmatter', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test Agent', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        forWebBundle: true,
+        skipActivation: true,
+      });
+
+      // Web bundle format has comment header
+      expect(xml).toContain('<!-- Powered by BMAD-CORE™ -->');
+      expect(xml).toContain('# Test Agent');
+      expect(xml).not.toMatch(/^---\n/);
+    });
+
+    it('should derive name from filename (remove .agent suffix)', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'pm', name: 'PM', title: 'Product Manager', icon: '📋' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        sourceFile: 'pm.agent.yaml',
+        skipActivation: true,
+      });
+
+      // Should convert pm.agent.yaml → "pm"
+      expect(xml).toContain('name: "pm"');
+    });
+
+    it('should convert hyphens to spaces in filename', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'cli', name: 'CLI', title: 'CLI Chief', icon: '⚙️' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        sourceFile: 'cli-chief.yaml',
+        skipActivation: true,
+      });
+
+      // Should convert cli-chief.yaml → "cli chief"
+      expect(xml).toContain('name: "cli chief"');
+    });
+  });
+
+  describe('localskip attribute', () => {
+    it('should add localskip="true" when metadata has localskip', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: {
+            id: 'web-only',
+            name: 'Web Only',
+            title: 'Web Only Agent',
+            icon: '🌐',
+            localskip: true,
+          },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('localskip="true"');
+    });
+
+    it('should not add localskip when false or missing', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).not.toContain('localskip=');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle empty menu array', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<menu>');
+      expect(xml).toContain('</menu>');
+      // Should still have injected *menu item
+      expect(xml).toContain('*menu');
+    });
+
+    it('should handle missing memories', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).not.toContain('<memories>');
+    });
+
+    it('should handle missing prompts', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).not.toContain('<prompts>');
+    });
+
+    it('should wrap XML in markdown code fence', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('```xml');
+      expect(xml).toContain('```\n');
+    });
+
+    it('should include activation instruction for installation format', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        sourceFile: 'test.yaml',
+        skipActivation: true,
+      });
+
+      expect(xml).toContain('You must fully embody this agent');
+      expect(xml).toContain('NEVER break character');
+    });
+
+    it('should not include activation instruction for web bundle', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        forWebBundle: true,
+        skipActivation: true,
+      });
+
+      expect(xml).not.toContain('You must fully embody');
+      expect(xml).toContain('<!-- Powered by BMAD-CORE™ -->');
+    });
+  });
+
+  describe('legacy commands field support', () => {
+    it('should handle legacy "commands" field (renamed to menu)', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          commands: [{ trigger: 'help', description: 'Help', action: 'show_help' }],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      expect(xml).toContain('<menu>');
+      // Should process commands as menu items
+    });
+
+    it('should prioritize menu over commands when both exist', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: {
+            role: 'Role',
+            identity: 'ID',
+            communication_style: 'Style',
+            principles: ['P'],
+          },
+          menu: [{ trigger: 'new', description: 'New', action: 'new_action' }],
+          commands: [{ trigger: 'old', description: 'Old', action: 'old_action' }],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, { skipActivation: true });
+
+      // Should use menu, not commands
+      expect(xml).toContain('<menu>');
+    });
+  });
+
+  describe('complete agent transformation', () => {
+    it('should transform a complete agent with all fields', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: {
+            id: 'full-agent',
+            name: 'Full Agent',
+            title: 'Complete Test Agent',
+            icon: '🤖',
+          },
+          persona: {
+            role: 'Full Stack Developer',
+            identity: 'Experienced software engineer',
+            communication_style: 'Clear and professional',
+            principles: ['Quality', 'Performance', 'Maintainability'],
+          },
+          memories: ['Remember project context', 'Track user preferences'],
+          prompts: [
+            { id: 'init', content: 'Initialize the agent' },
+            { id: 'task', content: 'Process the task' },
+          ],
+          critical_actions: ['Never delete data', 'Always backup'],
+          menu: [
+            { trigger: 'help', description: '[H] Show help', action: 'show_help' },
+            { trigger: 'start', description: '[S] Start workflow', workflow: 'main' },
+          ],
+        },
+      };
+
+      const xml = await builder.convertToXml(agentYaml, {
+        sourceFile: 'full-agent.yaml',
+        module: 'bmm',
+        skipActivation: true,
+      });
+
+      // Verify all sections are present
+      expect(xml).toContain('```xml');
+      expect(xml).toContain('<agent id="full-agent"');
+      expect(xml).toContain('<persona>');
+      expect(xml).toContain('<memories>');
+      expect(xml).toContain('<prompts>');
+      expect(xml).toContain('<menu>');
+      expect(xml).toContain('</agent>');
+      expect(xml).toContain('```');
+      // Verify persona content
+      expect(xml).toContain('Full Stack Developer');
+      // Verify memories
+      expect(xml).toContain('Remember project context');
+      // Verify prompts
+      expect(xml).toContain('Initialize the agent');
+    });
+  });
+});
--- a/test/unit/transformations/yaml-xml-builder.test.js
+++ b/test/unit/transformations/yaml-xml-builder.test.js
@ -0,0 +1,636 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { YamlXmlBuilder } from '../../../tools/cli/lib/yaml-xml-builder.js';
+import { createTempDir, cleanupTempDir, createTestFile } from '../../helpers/temp-dir.js';
+import fs from 'fs-extra';
+import path from 'node:path';
+import yaml from 'yaml';
+
+describe('YamlXmlBuilder', () => {
+  let tmpDir;
+  let builder;
+
+  beforeEach(async () => {
+    tmpDir = await createTempDir();
+    builder = new YamlXmlBuilder();
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tmpDir);
+  });
+
+  describe('deepMerge()', () => {
+    it('should merge shallow objects', () => {
+      const target = { a: 1, b: 2 };
+      const source = { b: 3, c: 4 };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result).toEqual({ a: 1, b: 3, c: 4 });
+    });
+
+    it('should merge nested objects', () => {
+      const target = { level1: { a: 1, b: 2 } };
+      const source = { level1: { b: 3, c: 4 } };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result).toEqual({ level1: { a: 1, b: 3, c: 4 } });
+    });
+
+    it('should merge deeply nested objects', () => {
+      const target = { l1: { l2: { l3: { value: 'old' } } } };
+      const source = { l1: { l2: { l3: { value: 'new', extra: 'data' } } } };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result).toEqual({ l1: { l2: { l3: { value: 'new', extra: 'data' } } } });
+    });
+
+    it('should append arrays instead of replacing', () => {
+      const target = { items: [1, 2, 3] };
+      const source = { items: [4, 5, 6] };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result.items).toEqual([1, 2, 3, 4, 5, 6]);
+    });
+
+    it('should handle arrays in nested objects', () => {
+      const target = { config: { values: ['a', 'b'] } };
+      const source = { config: { values: ['c', 'd'] } };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result.config.values).toEqual(['a', 'b', 'c', 'd']);
+    });
+
+    it('should replace arrays if target is not an array', () => {
+      const target = { items: 'string' };
+      const source = { items: ['a', 'b'] };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result.items).toEqual(['a', 'b']);
+    });
+
+    it('should handle null values', () => {
+      const target = { a: null, b: 2 };
+      const source = { a: 1, c: null };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result).toEqual({ a: 1, b: 2, c: null });
+    });
+
+    it('should preserve target values when source has no override', () => {
+      const target = { a: 1, b: 2, c: 3 };
+      const source = { d: 4 };
+
+      const result = builder.deepMerge(target, source);
+
+      expect(result).toEqual({ a: 1, b: 2, c: 3, d: 4 });
+    });
+
+    it('should not mutate original objects', () => {
+      const target = { a: 1 };
+      const source = { b: 2 };
+
+      builder.deepMerge(target, source);
+
+      expect(target).toEqual({ a: 1 }); // Unchanged
+      expect(source).toEqual({ b: 2 }); // Unchanged
+    });
+  });
+
+  describe('isObject()', () => {
+    it('should return true for plain objects', () => {
+      expect(builder.isObject({})).toBe(true);
+      expect(builder.isObject({ key: 'value' })).toBe(true);
+    });
+
+    it('should return false for arrays', () => {
+      expect(builder.isObject([])).toBe(false);
+      expect(builder.isObject([1, 2, 3])).toBe(false);
+    });
+
+    it('should return falsy for null', () => {
+      expect(builder.isObject(null)).toBeFalsy();
+    });
+
+    it('should return falsy for primitives', () => {
+      expect(builder.isObject('string')).toBeFalsy();
+      expect(builder.isObject(42)).toBeFalsy();
+      expect(builder.isObject(true)).toBeFalsy();
+      expect(builder.isObject()).toBeFalsy();
+    });
+  });
+
+  describe('loadAndMergeAgent()', () => {
+    it('should load agent YAML without customization', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test Agent', icon: '🔧' },
+          persona: {
+            role: 'Test Role',
+            identity: 'Test Identity',
+            communication_style: 'Professional',
+            principles: ['Principle 1'],
+          },
+          menu: [],
+        },
+      };
+
+      const agentPath = path.join(tmpDir, 'agent.yaml');
+      await fs.writeFile(agentPath, yaml.stringify(agentYaml));
+
+      const result = await builder.loadAndMergeAgent(agentPath);
+
+      expect(result.agent.metadata.id).toBe('test');
+      expect(result.agent.persona.role).toBe('Test Role');
+    });
+
+    it('should preserve base persona when customize has empty strings', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: {
+            role: 'Base Role',
+            identity: 'Base Identity',
+            communication_style: 'Base Style',
+            principles: ['Base Principle'],
+          },
+          menu: [],
+        },
+      };
+
+      const customizeYaml = {
+        persona: {
+          role: 'Custom Role',
+          identity: '', // Empty - should NOT override
+          communication_style: 'Custom Style',
+          // principles omitted
+        },
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.persona.role).toBe('Custom Role'); // Overridden
+      expect(result.agent.persona.identity).toBe('Base Identity'); // Preserved
+      expect(result.agent.persona.communication_style).toBe('Custom Style'); // Overridden
+      expect(result.agent.persona.principles).toEqual(['Base Principle']); // Preserved
+    });
+
+    it('should preserve base persona when customize has null values', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: {
+            role: 'Base Role',
+            identity: 'Base Identity',
+            communication_style: 'Base Style',
+            principles: ['Base'],
+          },
+          menu: [],
+        },
+      };
+
+      const customizeYaml = {
+        persona: {
+          role: null,
+          identity: 'Custom Identity',
+        },
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.persona.role).toBe('Base Role'); // Preserved (null skipped)
+      expect(result.agent.persona.identity).toBe('Custom Identity'); // Overridden
+    });
+
+    it('should preserve base persona when customize has empty arrays', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: {
+            role: 'Base Role',
+            identity: 'Base Identity',
+            communication_style: 'Base Style',
+            principles: ['Principle 1', 'Principle 2'],
+          },
+          menu: [],
+        },
+      };
+
+      const customizeYaml = {
+        persona: {
+          principles: [], // Empty array - should NOT override
+        },
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.persona.principles).toEqual(['Principle 1', 'Principle 2']);
+    });
+
+    it('should append menu items from customize', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: { role: 'Role', identity: 'ID', communication_style: 'Style', principles: ['P'] },
+          menu: [{ trigger: 'help', description: 'Help', action: 'show_help' }],
+        },
+      };
+
+      const customizeYaml = {
+        menu: [{ trigger: 'custom', description: 'Custom', action: 'custom_action' }],
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.menu).toHaveLength(2);
+      expect(result.agent.menu[0].trigger).toBe('help');
+      expect(result.agent.menu[1].trigger).toBe('custom');
+    });
+
+    it('should append critical_actions from customize', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: { role: 'Role', identity: 'ID', communication_style: 'Style', principles: ['P'] },
+          critical_actions: ['Action 1'],
+          menu: [],
+        },
+      };
+
+      const customizeYaml = {
+        critical_actions: ['Action 2', 'Action 3'],
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.critical_actions).toHaveLength(3);
+      expect(result.agent.critical_actions).toEqual(['Action 1', 'Action 2', 'Action 3']);
+    });
+
+    it('should append prompts from customize', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: { role: 'Role', identity: 'ID', communication_style: 'Style', principles: ['P'] },
+          prompts: [{ id: 'p1', content: 'Prompt 1' }],
+          menu: [],
+        },
+      };
+
+      const customizeYaml = {
+        prompts: [{ id: 'p2', content: 'Prompt 2' }],
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.prompts).toHaveLength(2);
+    });
+
+    it('should handle missing customization file', async () => {
+      const agentYaml = {
+        agent: {
+          metadata: { id: 'test', name: 'Test', title: 'Test', icon: '🔧' },
+          persona: { role: 'Role', identity: 'ID', communication_style: 'Style', principles: ['P'] },
+          menu: [],
+        },
+      };
+
+      const agentPath = path.join(tmpDir, 'agent.yaml');
+      await fs.writeFile(agentPath, yaml.stringify(agentYaml));
+
+      const nonExistent = path.join(tmpDir, 'nonexistent.yaml');
+      const result = await builder.loadAndMergeAgent(agentPath, nonExistent);
+
+      expect(result.agent.metadata.id).toBe('test');
+    });
+
+    it('should handle legacy commands field (renamed to menu)', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base', title: 'Base', icon: '🔧' },
+          persona: { role: 'Role', identity: 'ID', communication_style: 'Style', principles: ['P'] },
+          commands: [{ trigger: 'old', description: 'Old', action: 'old_action' }],
+        },
+      };
+
+      const customizeYaml = {
+        commands: [{ trigger: 'new', description: 'New', action: 'new_action' }],
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.commands).toHaveLength(2);
+    });
+
+    it('should override metadata with non-empty values', async () => {
+      const baseYaml = {
+        agent: {
+          metadata: { id: 'base', name: 'Base Name', title: 'Base Title', icon: '🔧' },
+          persona: { role: 'Role', identity: 'ID', communication_style: 'Style', principles: ['P'] },
+          menu: [],
+        },
+      };
+
+      const customizeYaml = {
+        agent: {
+          metadata: {
+            name: 'Custom Name',
+            title: '', // Empty - should be skipped
+            icon: '🎯',
+          },
+        },
+      };
+
+      const basePath = path.join(tmpDir, 'base.yaml');
+      const customizePath = path.join(tmpDir, 'customize.yaml');
+      await fs.writeFile(basePath, yaml.stringify(baseYaml));
+      await fs.writeFile(customizePath, yaml.stringify(customizeYaml));
+
+      const result = await builder.loadAndMergeAgent(basePath, customizePath);
+
+      expect(result.agent.metadata.name).toBe('Custom Name');
+      expect(result.agent.metadata.title).toBe('Base Title'); // Preserved
+      expect(result.agent.metadata.icon).toBe('🎯');
+    });
+  });
+
+  describe('buildPersonaXml()', () => {
+    it('should build complete persona XML', () => {
+      const persona = {
+        role: 'Test Role',
+        identity: 'Test Identity',
+        communication_style: 'Professional',
+        principles: ['Principle 1', 'Principle 2', 'Principle 3'],
+      };
+
+      const xml = builder.buildPersonaXml(persona);
+
+      expect(xml).toContain('<persona>');
+      expect(xml).toContain('</persona>');
+      expect(xml).toContain('<role>Test Role</role>');
+      expect(xml).toContain('<identity>Test Identity</identity>');
+      expect(xml).toContain('<communication_style>Professional</communication_style>');
+      expect(xml).toContain('<principles>Principle 1 Principle 2 Principle 3</principles>');
+    });
+
+    it('should escape XML special characters in persona', () => {
+      const persona = {
+        role: 'Role with <tags> & "quotes"',
+        identity: "O'Reilly's Identity",
+        communication_style: 'Use <code> tags',
+        principles: ['Principle with & ampersand'],
+      };
+
+      const xml = builder.buildPersonaXml(persona);
+
+      expect(xml).toContain('&lt;tags&gt; &amp; &quot;quotes&quot;');
+      expect(xml).toContain('O&apos;Reilly&apos;s Identity');
+      expect(xml).toContain('&lt;code&gt; tags');
+      expect(xml).toContain('&amp; ampersand');
+    });
+
+    it('should handle principles as array', () => {
+      const persona = {
+        role: 'Role',
+        identity: 'ID',
+        communication_style: 'Style',
+        principles: ['P1', 'P2', 'P3'],
+      };
+
+      const xml = builder.buildPersonaXml(persona);
+
+      expect(xml).toContain('<principles>P1 P2 P3</principles>');
+    });
+
+    it('should handle principles as string', () => {
+      const persona = {
+        role: 'Role',
+        identity: 'ID',
+        communication_style: 'Style',
+        principles: 'Single principle string',
+      };
+
+      const xml = builder.buildPersonaXml(persona);
+
+      expect(xml).toContain('<principles>Single principle string</principles>');
+    });
+
+    it('should preserve Unicode in persona fields', () => {
+      const persona = {
+        role: 'Тестовая роль',
+        identity: '日本語のアイデンティティ',
+        communication_style: 'Estilo profesional',
+        principles: ['原则一', 'Принцип два'],
+      };
+
+      const xml = builder.buildPersonaXml(persona);
+
+      expect(xml).toContain('Тестовая роль');
+      expect(xml).toContain('日本語のアイデンティティ');
+      expect(xml).toContain('Estilo profesional');
+      expect(xml).toContain('原则一 Принцип два');
+    });
+
+    it('should handle missing persona gracefully', () => {
+      const xml = builder.buildPersonaXml(null);
+
+      expect(xml).toBe('');
+    });
+
+    it('should handle partial persona (missing optional fields)', () => {
+      const persona = {
+        role: 'Role',
+        identity: 'ID',
+        communication_style: 'Style',
+        // principles missing
+      };
+
+      const xml = builder.buildPersonaXml(persona);
+
+      expect(xml).toContain('<role>Role</role>');
+      expect(xml).toContain('<identity>ID</identity>');
+      expect(xml).toContain('<communication_style>Style</communication_style>');
+      expect(xml).not.toContain('<principles>');
+    });
+  });
+
+  describe('buildMemoriesXml()', () => {
+    it('should build memories XML from array', () => {
+      const memories = ['Memory 1', 'Memory 2', 'Memory 3'];
+
+      const xml = builder.buildMemoriesXml(memories);
+
+      expect(xml).toContain('<memories>');
+      expect(xml).toContain('</memories>');
+      expect(xml).toContain('<memory>Memory 1</memory>');
+      expect(xml).toContain('<memory>Memory 2</memory>');
+      expect(xml).toContain('<memory>Memory 3</memory>');
+    });
+
+    it('should escape XML special characters in memories', () => {
+      const memories = ['Memory with <tags>', 'Memory with & ampersand', 'Memory with "quotes"'];
+
+      const xml = builder.buildMemoriesXml(memories);
+
+      expect(xml).toContain('&lt;tags&gt;');
+      expect(xml).toContain('&amp; ampersand');
+      expect(xml).toContain('&quot;quotes&quot;');
+    });
+
+    it('should return empty string for null memories', () => {
+      expect(builder.buildMemoriesXml(null)).toBe('');
+    });
+
+    it('should return empty string for empty array', () => {
+      expect(builder.buildMemoriesXml([])).toBe('');
+    });
+
+    it('should handle Unicode in memories', () => {
+      const memories = ['记忆 1', 'Память 2', '記憶 3'];
+
+      const xml = builder.buildMemoriesXml(memories);
+
+      expect(xml).toContain('记忆 1');
+      expect(xml).toContain('Память 2');
+      expect(xml).toContain('記憶 3');
+    });
+  });
+
+  describe('buildPromptsXml()', () => {
+    it('should build prompts XML from array format', () => {
+      const prompts = [
+        { id: 'p1', content: 'Prompt 1 content' },
+        { id: 'p2', content: 'Prompt 2 content' },
+      ];
+
+      const xml = builder.buildPromptsXml(prompts);
+
+      expect(xml).toContain('<prompts>');
+      expect(xml).toContain('</prompts>');
+      expect(xml).toContain('<prompt id="p1">');
+      expect(xml).toContain('<content>');
+      expect(xml).toContain('Prompt 1 content');
+      expect(xml).toContain('<prompt id="p2">');
+      expect(xml).toContain('Prompt 2 content');
+    });
+
+    it('should escape XML special characters in prompts', () => {
+      const prompts = [{ id: 'test', content: 'Content with <tags> & "quotes"' }];
+
+      const xml = builder.buildPromptsXml(prompts);
+
+      expect(xml).toContain('<content>');
+      expect(xml).toContain('&lt;tags&gt; &amp; &quot;quotes&quot;');
+    });
+
+    it('should return empty string for null prompts', () => {
+      expect(builder.buildPromptsXml(null)).toBe('');
+    });
+
+    it('should handle Unicode in prompts', () => {
+      const prompts = [{ id: 'unicode', content: 'Test 测试 тест テスト' }];
+
+      const xml = builder.buildPromptsXml(prompts);
+
+      expect(xml).toContain('<content>');
+      expect(xml).toContain('测试 тест テスト');
+    });
+
+    it('should handle object/dictionary format prompts', () => {
+      const prompts = {
+        p1: 'Prompt 1 content',
+        p2: 'Prompt 2 content',
+      };
+
+      const xml = builder.buildPromptsXml(prompts);
+
+      expect(xml).toContain('<prompts>');
+      expect(xml).toContain('<prompt id="p1">');
+      expect(xml).toContain('Prompt 1 content');
+      expect(xml).toContain('<prompt id="p2">');
+      expect(xml).toContain('Prompt 2 content');
+    });
+
+    it('should return empty string for empty array', () => {
+      expect(builder.buildPromptsXml([])).toBe('');
+    });
+  });
+
+  describe('calculateFileHash()', () => {
+    it('should calculate MD5 hash of file content', async () => {
+      const content = 'test content for hashing';
+      const filePath = await createTestFile(tmpDir, 'test.txt', content);
+
+      const hash = await builder.calculateFileHash(filePath);
+
+      expect(hash).toHaveLength(8); // MD5 truncated to 8 chars
+      expect(hash).toMatch(/^[a-f0-9]{8}$/);
+    });
+
+    it('should return consistent hash for same content', async () => {
+      const file1 = await createTestFile(tmpDir, 'file1.txt', 'content');
+      const file2 = await createTestFile(tmpDir, 'file2.txt', 'content');
+
+      const hash1 = await builder.calculateFileHash(file1);
+      const hash2 = await builder.calculateFileHash(file2);
+
+      expect(hash1).toBe(hash2);
+    });
+
+    it('should return null for non-existent file', async () => {
+      const nonExistent = path.join(tmpDir, 'missing.txt');
+
+      const hash = await builder.calculateFileHash(nonExistent);
+
+      expect(hash).toBeNull();
+    });
+
+    it('should handle empty file', async () => {
+      const file = await createTestFile(tmpDir, 'empty.txt', '');
+
+      const hash = await builder.calculateFileHash(file);
+
+      expect(hash).toHaveLength(8);
+    });
+  });
+});
--- a/test/unit/utils/xml-utils.test.js
+++ b/test/unit/utils/xml-utils.test.js
@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { escapeXml } from '../../../tools/lib/xml-utils.js';
+
+describe('xml-utils', () => {
+  describe('escapeXml()', () => {
+    it('should escape ampersand (&) to &amp;', () => {
+      expect(escapeXml('Tom & Jerry')).toBe('Tom &amp; Jerry');
+    });
+
+    it('should escape less than (<) to &lt;', () => {
+      expect(escapeXml('5 < 10')).toBe('5 &lt; 10');
+    });
+
+    it('should escape greater than (>) to &gt;', () => {
+      expect(escapeXml('10 > 5')).toBe('10 &gt; 5');
+    });
+
+    it('should escape double quote (") to &quot;', () => {
+      expect(escapeXml('He said "hello"')).toBe('He said &quot;hello&quot;');
+    });
+
+    it("should escape single quote (') to &apos;", () => {
+      expect(escapeXml("It's working")).toBe('It&apos;s working');
+    });
+
+    it('should preserve Unicode characters', () => {
+      expect(escapeXml('Hello 世界 🌍')).toBe('Hello 世界 🌍');
+    });
+
+    it('should escape multiple special characters in sequence', () => {
+      expect(escapeXml('<tag attr="value">')).toBe('&lt;tag attr=&quot;value&quot;&gt;');
+    });
+
+    it('should escape all five special characters together', () => {
+      expect(escapeXml(`&<>"'`)).toBe('&amp;&lt;&gt;&quot;&apos;');
+    });
+
+    it('should handle empty string', () => {
+      expect(escapeXml('')).toBe('');
+    });
+
+    it('should handle null', () => {
+      expect(escapeXml(null)).toBe('');
+    });
+
+    it('should handle undefined', () => {
+      expect(escapeXml()).toBe('');
+    });
+
+    it('should handle text with no special characters', () => {
+      expect(escapeXml('Hello World')).toBe('Hello World');
+    });
+
+    it('should handle text that is only special characters', () => {
+      expect(escapeXml('&&&')).toBe('&amp;&amp;&amp;');
+    });
+
+    it('should not double-escape already escaped entities', () => {
+      // Note: This is expected behavior - the function WILL double-escape
+      // This test documents the actual behavior
+      expect(escapeXml('&amp;')).toBe('&amp;amp;');
+    });
+
+    it('should escape special characters in XML content', () => {
+      const xmlContent = '<persona role="Developer & Architect">Use <code> tags</persona>';
+      const expected = '&lt;persona role=&quot;Developer &amp; Architect&quot;&gt;Use &lt;code&gt; tags&lt;/persona&gt;';
+      expect(escapeXml(xmlContent)).toBe(expected);
+    });
+
+    it('should handle mixed Unicode and special characters', () => {
+      expect(escapeXml('测试 <tag> & "quotes"')).toBe('测试 &lt;tag&gt; &amp; &quot;quotes&quot;');
+    });
+
+    it('should handle newlines and special characters', () => {
+      const multiline = 'Line 1 & text\n<Line 2>\n"Line 3"';
+      const expected = 'Line 1 &amp; text\n&lt;Line 2&gt;\n&quot;Line 3&quot;';
+      expect(escapeXml(multiline)).toBe(expected);
+    });
+
+    it('should handle string with only whitespace', () => {
+      expect(escapeXml('   ')).toBe('   ');
+    });
+  });
+});
--- a/vitest.config.js
+++ b/vitest.config.js
@ -0,0 +1,51 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    // Test file patterns
+    include: ['test/unit/**/*.test.js', 'test/integration/**/*.test.js'],
+    exclude: ['test/test-*.js', 'node_modules/**'],
+
+    // Timeouts
+    testTimeout: 10_000, // 10s for unit tests
+    hookTimeout: 30_000, // 30s for setup/teardown
+
+    // Parallel execution for speed
+    threads: true,
+    maxThreads: 4,
+
+    // Coverage configuration (using V8)
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'html', 'lcov', 'json-summary'],
+
+      // Files to include in coverage
+      include: ['tools/**/*.js', 'src/**/*.js'],
+
+      // Files to exclude from coverage
+      exclude: [
+        'test/**',
+        'tools/flattener/**', // Separate concern
+        'tools/bmad-npx-wrapper.js', // Entry point
+        'tools/build-docs.js', // Documentation tools
+        'tools/check-doc-links.js', // Documentation tools
+        '**/*.config.js', // Configuration files
+      ],
+
+      // Include all files for accurate coverage
+      all: true,
+
+      // Coverage thresholds (fail if below these)
+      statements: 85,
+      branches: 80,
+      functions: 85,
+      lines: 85,
+    },
+
+    // Global setup file
+    setupFiles: ['./test/setup.js'],
+
+    // Environment
+    environment: 'node',
+  },
+});