bmad-method-test-architecture-enterprise 2.0.4-next.4 → 3.0.0

package/.claude-plugin/marketplace.json

@@ -30,22 +30,22 @@
     {
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
-      "description": "Master Test Architect module for quality strategy, test generation in red and expand modes with automatic run-and-heal, combined framework and CI setup, CI/CD quality gates, and structured testing education. The CI and ATDD commands remain available with existing customizations. Part of the BMad Method ecosystem.",
-      "version": "2.0.4-next.4",
+      "description": "Master Test Architect module for quality strategy, test generation in red and expand modes with automatic run-and-heal, combined framework and CI setup, CI/CD quality gates, and structured testing education. Existing CI and ATDD customizations can be migrated to the new skill names. Part of the BMad Method ecosystem.",
+      "version": "3.0.0",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },
       "skills": [
         "./skills/bmod-tea",
         "./skills/bmad-tea",
-        "./skills/bmad-testarch-automate",
-        "./skills/bmad-testarch-evaluate",
-        "./skills/bmad-testarch-framework",
-        "./skills/bmad-testarch-nfr",
-        "./skills/bmad-testarch-test-design",
-        "./skills/bmad-testarch-test-review",
-        "./skills/bmad-testarch-trace",
-        "./skills/bmad-teach-me-testing"
+        "./skills/bmad-tea-automate",
+        "./skills/bmad-tea-evaluate",
+        "./skills/bmad-tea-framework",
+        "./skills/bmad-tea-nfr",
+        "./skills/bmad-tea-test-design",
+        "./skills/bmad-tea-test-review",
+        "./skills/bmad-tea-trace",
+        "./skills/bmad-tea-teach-me-testing"
       ]
     }
   ]

package/README.md

@@ -46,37 +46,52 @@ To install a tagged release, replace `<version>` with the release number:
 npx skills add https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/tree/v<version>/skills
 ```
 
+### Upgrading to 3.0
+
+The eight direct workflow commands now share the `bmad-tea-*` prefix. Replace `bmad-testarch-automate`, `-evaluate`, `-framework`, `-nfr`, `-test-design`, `-test-review`, and `-trace` with the same suffix under `bmad-tea-`. Replace `bmad-teach-me-testing` with `bmad-tea-teach-me-testing`. The 3.0 package does not publish the old slash commands. The `bmad-tea` agent, `bmod-tea` module, menu codes, and `tea-*` CLI executables keep their names.
+
+After installing 3.0, move project customizations to the new names:
+
+```bash
+npx --package=bmad-method-test-architecture-enterprise@3 tea-migrate-customizations --project-root . --check
+npx --package=bmad-method-test-architecture-enterprise@3 tea-migrate-customizations --project-root .
+```
+
+This includes old CI and ATDD customization files and old skill references in custom `bmad-tea` agent menus. The command moves old-only files with their comments and permissions intact. When both old and new filenames exist, it reports both paths and asks for a manual merge so no comments or values are lost. Resolve the reported files, then rerun the command. See the [configuration reference](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/configuration/) for details.
+
+An existing host may retain the old skill folders after installing 3.0. Check the host's project and global skills folders, back up any edits in the old folders, and move those eight folders out of skill discovery. The [troubleshooting guide](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/reference/troubleshooting/#old-slash-commands-still-appear-after-30) lists the exact folders and a safe cleanup sequence. Restart the host so its command list refreshes.
+
 <a id="start-with-one-workflow"></a>
 
 ## Start with one skill
 
 Eight commands start the eight workflows: Framework includes CI setup; Automate includes red and expand modes.
 
-In Claude Code, Cursor, and Windsurf, type `/bmad-testarch-test-design` in chat.
-In Codex, type `$bmad-testarch-test-design`.
+In Claude Code, Cursor, and Windsurf, type `/bmad-tea-test-design` in chat.
+In Codex, type `$bmad-tea-test-design`.
 You can also load `/bmad-tea` or `$bmad-tea` and choose a menu code.
 Each skill can run directly in a fresh session.
 
 | Skill                                                                                                                           | Command                      | Menu | Use it to                                            |
 | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ---- | ---------------------------------------------------- |
-| [Automate](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-automate/)             | `/bmad-testarch-automate`    | TA   | Generate red acceptance scaffolds or expand coverage |
-| [Test Review](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-test-review/)       | `/bmad-testarch-test-review` | RV   | Audit test quality and score findings                |
-| [Test Design](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-test-design/)       | `/bmad-testarch-test-design` | TD   | Plan risks, coverage, and NFR evidence               |
-| [Framework](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/setup-test-framework/)    | `/bmad-testarch-framework`   | TF   | Set up a test framework, CI, or both                 |
-| [NFR](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-nfr-assess/)                | `/bmad-testarch-nfr`         | NR   | Audit implemented NFR evidence                       |
-| [Trace](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-trace/)                   | `/bmad-testarch-trace`       | TR   | Map requirements to tests and decide a release gate  |
-| [Teach Me Testing](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/teach-me-testing/) | `/bmad-teach-me-testing`     | TMT  | Learn testing through seven sessions                 |
+| [Automate](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-automate/)             | `/bmad-tea-automate`         | TA   | Generate red acceptance scaffolds or expand coverage |
+| [Test Review](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-test-review/)       | `/bmad-tea-test-review`      | RV   | Audit test quality and score findings                |
+| [Test Design](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-test-design/)       | `/bmad-tea-test-design`      | TD   | Plan risks, coverage, and NFR evidence               |
+| [Framework](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/setup-test-framework/)    | `/bmad-tea-framework`        | TF   | Set up a test framework, CI, or both                 |
+| [NFR](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-nfr-assess/)                | `/bmad-tea-nfr`              | NR   | Audit implemented NFR evidence                       |
+| [Trace](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/run-trace/)                   | `/bmad-tea-trace`            | TR   | Map requirements to tests and decide a release gate  |
+| [Teach Me Testing](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/how-to/workflows/teach-me-testing/) | `/bmad-tea-teach-me-testing` | TMT  | Learn testing through seven sessions                 |
 
 Evaluate:
 
-- [Evaluate](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/tutorials/evaluate-your-first-skill/): `/bmad-testarch-evaluate`, menu `EV`. Build and run a behavioral evaluation.
+- [Evaluate](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/tutorials/evaluate-your-first-skill/): `/bmad-tea-evaluate`, menu `EV`. Build and run a behavioral evaluation.
 
-Framework and CI setup share one skill, `bmad-testarch-framework`.
+Framework and CI setup share one skill, `bmad-tea-framework`.
 Ask for framework only, CI only, or both; TEA infers the scope from your prompt and asks "Do you want CI too?" once when CI scope is unclear in an interactive session. An unattended request with unclear scope runs framework setup only and states that CI was excluded.
-Request CI setup through `/bmad-testarch-framework` or the agent's `CI` menu code. Existing CI customizations remain usable.
+Request CI setup through `/bmad-tea-framework` or the agent's `CI` menu code. Migrated CI customizations remain usable.
 Create, Resume, Validate, and Edit remain available for the selected setup scope.
 
-Automation uses `red` mode before implementation and `expand` mode for existing code. Request red mode through `/bmad-testarch-automate` or the agent's `AT` menu code; the direct command defaults to expand. Existing customization files and saved progress remain usable. Create runs execute the generated tests and repair test issues for up to three rounds. Red confirms the intended missing behavior; expand aims for passing coverage and reports product defects.
+Automation uses `red` mode before implementation and `expand` mode for existing code. Request red mode through `/bmad-tea-automate` or the agent's `AT` menu code; the direct command defaults to expand. Migrated customization files and saved progress remain usable. Create runs execute the generated tests and repair test issues for up to three rounds. Red confirms the intended missing behavior; expand aims for passing coverage and reports product defects.
 
 For Codex, replace the leading `/` in the table with `$`.
 The agent menu also accepts `GATE` to route you through test review, NFR evidence audit, and trace Phase 2.

package/cli/atdd-red-check.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * tea-atdd-red-check — activates and executes the scaffolds
- * `bmad-testarch-atdd` wrote, and reports what actually happened.
+ * `bmad-tea-atdd` wrote, and reports what actually happened.
  *
  * This is the deterministic half of the ATDD suite, and it carries no vendor
  * knowledge at all: it never calls a model, never resolves a credential, and

package/cli/atdd-runner.js

@@ -3,7 +3,7 @@
  * tea-atdd-runner — the command the ATDD behavioral contract names for
  * generation.
  *
- * `bmad-testarch-atdd` reads a story's acceptance criteria and writes red-phase
+ * `bmad-tea-atdd` reads a story's acceptance criteria and writes red-phase
  * test scaffolds under the project's `tests/` directory, one deliverable this
  * eval measures by executing rather than reading. Generation and execution are
  * two separate commands: this one drives the workflow and leaves the scaffolds

package/cli/automate.js

@@ -135,11 +135,11 @@ async function main(argv) {
     if (options.projectSkill) {
       const candidates = ['.claude/skills', '.agents/skills', 'skills', '_bmad/tea/workflows/testarch'];
       options.skillRoot = candidates
-        .map((directory) => path.join(root, directory, 'bmad-testarch-automate'))
+        .map((directory) => path.join(root, directory, 'bmad-tea-automate'))
         .find((candidate) => fs.existsSync(path.join(candidate, 'SKILL.md')));
-      if (!options.skillRoot) throw new Error('project-installed bmad-testarch-automate skill is missing');
+      if (!options.skillRoot) throw new Error('project-installed bmad-tea-automate skill is missing');
     }
-    skillRoot = resolveWorkflowSkill({ projectRoot: root, skillName: 'bmad-testarch-automate', skillRoot: options.skillRoot });
+    skillRoot = resolveWorkflowSkill({ projectRoot: root, skillName: 'bmad-tea-automate', skillRoot: options.skillRoot });
     if (!fs.existsSync(path.join(skillRoot, '..', 'bmod-tea', 'knowledge', 'tea-index.csv')))
       throw new Error('the selected skill has no sibling bmod-tea knowledge base');
     if (options.story) story = artifactPath(root, options.story, '--story');

package/cli/ci-runner.js

@@ -2,7 +2,7 @@
 /**
  * tea-ci-runner: the command the CI behavioral contract names.
  *
- * `bmad-testarch-ci` scaffolds a pipeline for the project it is run in and
+ * `bmad-tea-ci` scaffolds a pipeline for the project it is run in and
  * writes one deliverable a linter can hold to account, the platform's own
  * workflow file, which for GitHub Actions is `.github/workflows/test.yml`.
  * Measuring that needs a command to point at, and this file is that command.

package/cli/lib/automate-prompt.js

@@ -27,7 +27,7 @@ function resolveGenerationConfig(projectRoot, checkpointPath, operation, skillRo
   };
   if (!['none', 'auto', 'cli', 'mcp'].includes(tea.tea_browser_automation))
     throw new Error('tea_browser_automation must be none, auto, cli or mcp');
-  const namespace = mode === 'red' ? 'bmad-testarch-atdd' : 'bmad-testarch-automate';
+  const namespace = mode === 'red' ? 'bmad-tea-atdd' : 'bmad-tea-automate';
   const sibling = path.join(skillRoot, '..', namespace, 'customize.toml');
   const defaultsPath =
     mode === 'red' && !fs.existsSync(sibling)

package/cli/lib/framework-setup.js

@@ -12,7 +12,7 @@ const { spawnSync } = require('node:child_process');
 const { runAgent } = require('./run-agent');
 const { resolveTeaConfig } = require('./resolve-tea-config');
 
-const SKILL_NAME = 'bmad-testarch-framework';
+const SKILL_NAME = 'bmad-tea-framework';
 const SCOPES = ['framework', 'ci', 'both'];
 const OPERATIONS = ['create', 'resume', 'validate', 'edit'];
 
@@ -607,7 +607,7 @@ function prepareSetup({ projectRoot, skillRoot, config, options }) {
     throw problem('Resume has an uncertain started hook. Record explicit operator recovery in the journal before headless execution.');
   const scope = options.operation === 'resume' ? before.data.setup_scope : options.scope;
   const ciConfig = ['ci', 'both'].includes(scope)
-    ? resolveTeaConfig({ projectRoot, skillRoot: path.join(skillRoot, '..', 'bmad-testarch-ci'), skillName: 'bmad-testarch-ci' })
+    ? resolveTeaConfig({ projectRoot, skillRoot: path.join(skillRoot, 'ci'), skillName: 'bmad-tea-ci' })
     : null;
   const requiredHooks = {};
   for (const [phase, settings] of [

package/cli/lib/resolve-skill.js

@@ -1,5 +1,5 @@
 /**
- * Resolve the installed bmad-testarch-test-review skill root inside a consuming project.
+ * Resolve the installed bmad-tea-test-review skill root inside a consuming project.
  *
  * Probe order mirrors BMAD installer outputs: BMAD core layout, Claude Code, Codex.
  * The skill remains the source of truth for review logic; the CLI only locates it.
@@ -8,7 +8,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const SKILL_NAME = 'bmad-testarch-test-review';
+const SKILL_NAME = 'bmad-tea-test-review';
 
 // The classic installer's location comes last: a project upgraded from v6 can still hold that copy, and it must not shadow the skill the v7 install added.
 const SKILL_CANDIDATES = [

package/cli/lib/resolve-tea-config.js

@@ -285,7 +285,7 @@ function parseToml(content, label) {
 }
 
 /** Resolve trusted skill defaults and project workflow overrides from the same configuration source. */
-function readWorkflowCustomization(source, skillRoot, projectRoot, skillName = 'bmad-testarch-test-review') {
+function readWorkflowCustomization(source, skillRoot, projectRoot, skillName = 'bmad-tea-test-review') {
   if (!skillRoot) return {};
   const defaultsPath = path.join(skillRoot, 'customize.toml');
   source.recordInput?.(defaultsPath);
@@ -296,10 +296,24 @@ function readWorkflowCustomization(source, skillRoot, projectRoot, skillName = '
     if (error.code !== 'ENOENT') throw configError(`Failed to load ${defaultsPath}: ${error.message}`);
   }
   if (!/^[a-z0-9][a-z0-9-]*$/.test(skillName)) throw configError('Workflow skill name must be a lowercase kebab-case name');
-  const workflowPaths = ['.toml', '.user.toml'].map((suffix) => path.join('_bmad', 'custom', skillName + suffix));
-  for (const relativePath of workflowPaths) {
-    const content = source.read(relativePath);
-    if (content !== null) merged = mergeTables(merged, parseToml(content, source.label(relativePath)));
+  const oldName =
+    skillName === 'bmad-tea-teach-me-testing'
+      ? 'bmad-teach-me-testing'
+      : skillName.startsWith('bmad-tea-')
+        ? skillName.replace('bmad-tea-', 'bmad-testarch-')
+        : null;
+  for (const suffix of ['.toml', '.user.toml']) {
+    const legacyPath = oldName && path.join('_bmad', 'custom', oldName + suffix);
+    const currentPath = path.join('_bmad', 'custom', skillName + suffix);
+    const legacyContent = legacyPath && source.read(legacyPath);
+    const currentContent = source.read(currentPath);
+    const legacy = legacyContent === null ? {} : parseToml(legacyContent, source.label(legacyPath));
+    const current = currentContent === null ? {} : parseToml(currentContent, source.label(currentPath));
+    const conflict = conflictingValue(legacy, current);
+    if (conflict) {
+      throw configError(`Conflicting workflow customization ${conflict} in ${source.label(legacyPath)} and ${source.label(currentPath)}`);
+    }
+    merged = mergeTables(merged, unionEqualCustomizationValues(legacy, current));
   }
   if (merged.workflow !== undefined && !isPlainObject(merged.workflow)) {
     throw configError('Workflow customization must contain a [workflow] table');
@@ -327,6 +341,29 @@ function readWorkflowCustomization(source, skillRoot, projectRoot, skillName = '
   return workflow;
 }
 
+/** Find the first setting whose legacy and current values disagree. */
+function conflictingValue(legacy, current, prefix = '') {
+  for (const [key, oldValue] of Object.entries(legacy)) {
+    if (!Object.hasOwn(current, key)) continue;
+    const next = prefix ? `${prefix}.${key}` : key;
+    const newValue = current[key];
+    if (isPlainObject(oldValue) && isPlainObject(newValue)) {
+      const nested = conflictingValue(oldValue, newValue, next);
+      if (nested) return nested;
+    } else if (JSON.stringify(oldValue) !== JSON.stringify(newValue)) return next;
+  }
+  return null;
+}
+
+/** Combine old and new names for one layer without appending an identical array twice. */
+function unionEqualCustomizationValues(legacy, current) {
+  const result = { ...legacy };
+  for (const [key, value] of Object.entries(current)) {
+    result[key] = isPlainObject(result[key]) && isPlainObject(value) ? unionEqualCustomizationValues(result[key], value) : value;
+  }
+  return result;
+}
+
 /** Coerce the keys this CLI cares about out of a raw TEA config table. */
 function pickTeaValues(table, source) {
   const values = {};

package/cli/lib/test-design-parser.js

@@ -74,7 +74,7 @@ function isReferenceHeading(heading) {
  *   second risk table, an explanatory sentence, an HTML comment). `Reference:` and
  *   `References:` open citations, so they label nothing; so does `For example:`.
  *
- * The shipped worked example, `bmad-testarch-test-design/resources/test-design-epic-3.example.md`,
+ * The shipped worked example, `bmad-tea-test-design/resources/test-design-epic-3.example.md`,
  * shows the register this rule keeps: the three band tables under `## Risk Assessment`
  * (`### High Risks: Score 6 or Greater`, `### Medium Risks: Score 3 to 4`,
  * `### Low Risks: Score 1 to 2`), none of whose headings or lead-ins labels anything.

package/cli/lib/workflow-cli.js

@@ -111,7 +111,11 @@ function resolveWorkflowSkill({ projectRoot, skillName, skillRoot }) {
     if (!fs.statSync(path.join(knowledge, 'tea-index.csv')).isFile()) throw new Error('sibling bmod-tea knowledge is missing');
     return fs.realpathSync(root);
   } catch (error) {
-    throw new WorkflowError('environment-configuration', `${skillName} is unavailable at ${root}: ${error.message}`, { cause: error });
+    throw new WorkflowError(
+      'environment-configuration',
+      `${skillName} is unavailable at ${root}: ${error.message}. Install TEA with npx skills add bmad-code-org/bmad-method-test-architecture-enterprise`,
+      { cause: error },
+    );
   }
 }
 /** Activate the actual skill using authoritative config and caller run inputs. */

package/cli/migrate-customizations.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+/** Move pre-3.0 TEA customization files and menu references to canonical names. */
+const fs = require('node:fs');
+const path = require('node:path');
+const { isDeepStrictEqual } = require('node:util');
+const TOML = require('smol-toml');
+
+const NAMES = ['automate', 'evaluate', 'framework', 'nfr', 'test-design', 'test-review', 'trace', 'atdd', 'ci'];
+const PAIRS = [
+  ...NAMES.map((suffix) => [`bmad-testarch-${suffix}`, `bmad-tea-${suffix}`]),
+  ['bmad-teach-me-testing', 'bmad-tea-teach-me-testing'],
+];
+const MENU_NAMES = new Map(PAIRS);
+MENU_NAMES.set('bmad-testarch-atdd', 'bmad-tea-automate');
+MENU_NAMES.set('bmad-testarch-ci', 'bmad-tea-framework');
+
+function isTable(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date);
+}
+
+function conflictAt(oldValue, newValue, key = '') {
+  for (const [name, value] of Object.entries(oldValue)) {
+    if (!Object.hasOwn(newValue, name)) continue;
+    const location = key ? `${key}.${name}` : name;
+    if (isTable(value) && isTable(newValue[name])) {
+      const nested = conflictAt(value, newValue[name], location);
+      if (nested) return nested;
+    } else if (!isDeepStrictEqual(value, newValue[name])) return location;
+  }
+  return null;
+}
+
+function parse(file, source) {
+  try {
+    return TOML.parse(source);
+  } catch (error) {
+    throw new Error(`Cannot parse ${file}: ${error.message}`);
+  }
+}
+
+/** Reject links and non-files before any content is read or changed. */
+function readFile(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot inspect ${file}: ${error.message}`);
+  }
+  if (!stat.isFile() || stat.isSymbolicLink())
+    throw new Error(`Customization path must be a regular file, not a symlink or special file: ${file}`);
+  return { file, stat, text: fs.readFileSync(file, 'utf8') };
+}
+
+function checkDirectory(directory, required = false) {
+  let stat;
+  try {
+    stat = fs.lstatSync(directory);
+  } catch (error) {
+    if (error.code === 'ENOENT' && !required) return false;
+    if (error.code === 'ENOENT') throw new Error(`Project root does not exist: ${directory}`);
+    throw new Error(`Cannot inspect ${directory}: ${error.message}`);
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Customization path must be a real directory: ${directory}`);
+  return true;
+}
+
+/** Edit only skill assignments inside agent menu entries, retaining every other byte. */
+function rewriteMenu(file, source) {
+  const original = parse(file, source);
+  const menus = original.agent?.menu;
+  if (menus !== undefined && !Array.isArray(menus)) throw new Error(`Expected [[agent.menu]] entries in ${file}`);
+  const expected = structuredClone(original);
+  let expectedChanges = 0;
+  for (const menu of expected.agent?.menu ?? []) {
+    if (typeof menu.skill !== 'string' || !(menu.skill.startsWith('bmad-testarch-') || menu.skill === 'bmad-teach-me-testing')) continue;
+    const replacement = MENU_NAMES.get(menu.skill);
+    if (!replacement) throw new Error(`Unknown legacy menu skill ${JSON.stringify(menu.skill)} in ${file}; update it manually`);
+    menu.skill = replacement;
+    expectedChanges++;
+  }
+  if (expectedChanges === 0) return null;
+  let inMenu = false;
+  let actualChanges = 0;
+  const lines = source.split(/(\r?\n)/);
+  for (let index = 0; index < lines.length; index += 2) {
+    const line = lines[index];
+    if (/^\s*\[/.test(line)) inMenu = /^\s*\[\[agent\.menu\]\]\s*(?:#.*)?$/.test(line);
+    if (!inMenu) continue;
+    const match = /^(\s*skill\s*=\s*)(["'])([^"']+)\2(\s*(?:#.*)?)$/.exec(line);
+    if (!match || !MENU_NAMES.has(match[3])) continue;
+    lines[index] = `${match[1]}${match[2]}${MENU_NAMES.get(match[3])}${match[2]}${match[4]}`;
+    actualChanges++;
+  }
+  const rewritten = lines.join('');
+  if (actualChanges !== expectedChanges || !isDeepStrictEqual(parse(file, rewritten), expected)) {
+    throw new Error(`Cannot safely rewrite legacy menu skill references in ${file}; update them manually`);
+  }
+  return rewritten;
+}
+
+function preflight(customRoot) {
+  const actions = [];
+  for (const [oldName, newName] of PAIRS) {
+    for (const suffix of ['.toml', '.user.toml']) {
+      const oldFile = path.join(customRoot, oldName + suffix);
+      const newFile = path.join(customRoot, newName + suffix);
+      const old = readFile(oldFile);
+      const current = readFile(newFile);
+      if (!old) continue;
+      const oldValue = parse(oldFile, old.text);
+      if (current) {
+        const newValue = parse(newFile, current.text);
+        const conflict = conflictAt(oldValue, newValue);
+        if (conflict) throw new Error(`Conflicting ${conflict} in ${oldFile} and ${newFile}`);
+        throw new Error(
+          `Both ${oldFile} and ${newFile} exist. Merge their values and comments manually into ${newFile}, then remove ${oldFile} and rerun.`,
+        );
+      }
+      actions.push({ kind: 'move', oldFile, newFile, old });
+    }
+  }
+  for (const suffix of ['.toml', '.user.toml']) {
+    const file = path.join(customRoot, 'bmad-tea' + suffix);
+    const old = readFile(file);
+    if (!old) continue;
+    const rewritten = rewriteMenu(file, old.text);
+    if (rewritten !== null) actions.push({ kind: 'rewrite', oldFile: file, newFile: file, old, text: rewritten });
+  }
+  return actions;
+}
+
+function unchanged(snapshot) {
+  const current = readFile(snapshot.file);
+  return (
+    current !== null &&
+    current.stat.dev === snapshot.stat.dev &&
+    current.stat.ino === snapshot.stat.ino &&
+    current.stat.mode === snapshot.stat.mode &&
+    current.text === snapshot.text
+  );
+}
+
+/** Apply staged changes under one exclusive lock and undo completed actions on failure. */
+function applyActions(actions, customRoot, beforeAction) {
+  const completed = [];
+  const temporary = [];
+  let rollbackSafe = true;
+  try {
+    for (const [index, action] of actions.entries()) {
+      if (action.kind !== 'rewrite') continue;
+      const temp = path.join(customRoot, `.tea-migration-${process.pid}-${index}.tmp`);
+      fs.writeFileSync(temp, action.text, { flag: 'wx', mode: action.old.stat.mode & 0o777 });
+      fs.chmodSync(temp, action.old.stat.mode & 0o777);
+      action.temp = temp;
+      temporary.push(temp);
+    }
+    for (const [index, action] of actions.entries()) {
+      beforeAction?.(action, index);
+      if (!unchanged(action.old)) throw new Error(`Customization changed during migration: ${action.oldFile}`);
+      if (action.kind === 'move') {
+        if (readFile(action.newFile) !== null) throw new Error(`Customization appeared during migration: ${action.newFile}`);
+        fs.linkSync(action.oldFile, action.newFile);
+        completed.push(action);
+        fs.unlinkSync(action.oldFile);
+      } else {
+        const backup = path.join(customRoot, `.tea-migration-${process.pid}-${index}.bak`);
+        fs.linkSync(action.oldFile, backup);
+        action.backup = backup;
+        completed.push(action);
+        fs.renameSync(action.temp, action.oldFile);
+      }
+    }
+  } catch (error) {
+    const rollbackErrors = [];
+    for (const action of completed.toReversed()) {
+      try {
+        if (action.kind === 'move') {
+          if (!fs.existsSync(action.oldFile)) fs.linkSync(action.newFile, action.oldFile);
+          fs.unlinkSync(action.newFile);
+        } else {
+          if (fs.existsSync(action.oldFile)) fs.unlinkSync(action.oldFile);
+          fs.linkSync(action.backup, action.oldFile);
+          fs.unlinkSync(action.backup);
+        }
+      } catch (rollbackError) {
+        rollbackErrors.push(`${action.oldFile}: ${rollbackError.message}`);
+      }
+    }
+    rollbackSafe = rollbackErrors.length === 0;
+    throw new Error(`${error.message}${rollbackErrors.length > 0 ? `; rollback needs manual repair: ${rollbackErrors.join('; ')}` : ''}`);
+  } finally {
+    if (rollbackSafe) for (const action of actions) if (action.backup && fs.existsSync(action.backup)) fs.unlinkSync(action.backup);
+    for (const temp of temporary) if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+}
+
+function migrate(projectRoot, { check = false, beforeAction } = {}) {
+  const root = path.resolve(projectRoot);
+  checkDirectory(root, true);
+  const bmadRoot = path.join(root, '_bmad');
+  if (!checkDirectory(bmadRoot)) return [];
+  const customRoot = path.join(bmadRoot, 'custom');
+  if (!checkDirectory(customRoot)) return [];
+  if (check) return preflight(customRoot);
+  const lock = path.join(customRoot, '.tea-migration.lock');
+  try {
+    fs.mkdirSync(lock, { mode: 0o700 });
+  } catch (error) {
+    if (error.code === 'EEXIST') {
+      throw new Error(
+        `Migration lock exists at ${lock}. Check for a running migration; if none is running, inspect and remove the stale lock directory, then retry.`,
+      );
+    }
+    throw new Error(`Cannot lock ${customRoot} for migration: ${error.message}`);
+  }
+  try {
+    const actions = preflight(customRoot);
+    applyActions(actions, customRoot, beforeAction);
+    return actions;
+  } finally {
+    fs.rmdirSync(lock);
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const usage = 'Usage: tea-migrate-customizations [--project-root PATH] [--check]';
+  const rootIndex = argv.indexOf('--project-root');
+  if (rootIndex !== -1 && (!argv[rootIndex + 1] || argv[rootIndex + 1].startsWith('--'))) throw new Error('--project-root requires a path');
+  if (argv.some((arg, index) => arg !== '--check' && arg !== '--project-root' && index !== rootIndex + 1)) throw new Error(usage);
+  const projectRoot = rootIndex < 0 ? process.cwd() : path.resolve(argv[rootIndex + 1]);
+  const check = argv.includes('--check');
+  const actions = migrate(projectRoot, { check });
+  for (const action of actions) {
+    process.stdout.write(
+      action.kind === 'rewrite'
+        ? `${check ? 'Would update' : 'Updated'} menu references in ${action.oldFile}\n`
+        : `${check ? 'Would move ' : ''}${action.oldFile} -> ${action.newFile}\n`,
+    );
+  }
+  if (actions.length === 0) process.stdout.write('No legacy TEA customizations found.\n');
+  return 0;
+}
+
+if (require.main === module) {
+  try {
+    process.exitCode = main();
+  } catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 2;
+  }
+}
+
+module.exports = { migrate, main };

package/cli/nfr-runner.js

@@ -2,7 +2,7 @@
 /**
  * tea-nfr-runner — the command the NFR behavioral contract names.
  *
- * `bmad-testarch-nfr` audits the evidence a team already holds and writes one
+ * `bmad-tea-nfr` audits the evidence a team already holds and writes one
  * deliverable, `{test_artifacts}/nfr/nfr-assessment-{run_key}.md`. Measuring that needs a
  * command to point at, and TEA shipped none: `tea-test-review`,
  * `tea-fragment-selection-runner`, and `tea-trace-runner` all exist and an NFR

package/cli/nfr.js

@@ -95,8 +95,8 @@ function run(argv) {
   )
     throw new WorkflowError('usage', 'requirement inputs cannot also be implementation evidence');
   const protection = protectSources(projectRoot, [...inputs, ...options.implementation, ...options.evidence]);
-  const skillRoot = resolveWorkflowSkill({ projectRoot, skillName: 'bmad-testarch-nfr', skillRoot: options.skillRoot });
-  const resolvedConfig = resolveTeaConfig({ projectRoot, skillRoot, skillName: 'bmad-testarch-nfr' });
+  const skillRoot = resolveWorkflowSkill({ projectRoot, skillName: 'bmad-tea-nfr', skillRoot: options.skillRoot });
+  const resolvedConfig = resolveTeaConfig({ projectRoot, skillRoot, skillName: 'bmad-tea-nfr' });
   const artifactRoot = options.outputDir ?? resolvedConfig.configSnapshot.modules.tea.test_artifacts;
   if (typeof artifactRoot !== 'string' || !artifactRoot.trim())
     throw new WorkflowError('environment-configuration', '--output-dir or TEA test_artifacts must be a nonempty string');

package/cli/teach.js

@@ -106,13 +106,13 @@ function run(argv = process.argv) {
   const inputFile = options.messageFile ? readInput(root, options.messageFile, '--message-file') : null;
   const message = inputFile ? new TextDecoder('utf-8', { fatal: true }).decode(fs.readFileSync(inputFile)) : options.message;
   if (!message.trim()) throw new WorkflowError('usage', 'learner message must be nonempty');
-  const skillRoot = resolveWorkflowSkill({ projectRoot: root, skillName: 'bmad-teach-me-testing', skillRoot: options.skillRoot });
+  const skillRoot = resolveWorkflowSkill({ projectRoot: root, skillName: 'bmad-tea-teach-me-testing', skillRoot: options.skillRoot });
   const consumedInputs = new Set();
   const inputPatterns = new Map();
   const config = resolveTeaConfig({
     projectRoot: root,
     skillRoot,
-    skillName: 'bmad-teach-me-testing',
+    skillName: 'bmad-tea-teach-me-testing',
     inputPaths: consumedInputs,
     inputPatterns,
   });
@@ -149,8 +149,8 @@ function run(argv = process.argv) {
       '_bmad/custom/config.user.toml',
       'package.json',
       'package-lock.json',
-      '_bmad/custom/bmad-teach-me-testing.toml',
-      '_bmad/custom/bmad-teach-me-testing.user.toml',
+      '_bmad/custom/bmad-tea-teach-me-testing.toml',
+      '_bmad/custom/bmad-tea-teach-me-testing.user.toml',
     ].map((file) => path.join(root, file)),
   ].filter(Boolean);
   const guard = () => {

package/cli/test-design.js

@@ -324,8 +324,8 @@ function run(argv) {
   if (options.scope === 'system' && inputs.length < 2)
     throw new WorkflowError('usage', 'system scope requires two distinct input documents');
   const inputDigests = inputs.map((file) => [file, digest(file)]);
-  const skillRoot = resolveWorkflowSkill({ projectRoot, skillName: 'bmad-testarch-test-design', skillRoot: options.skillRoot });
-  const resolvedConfig = resolveTeaConfig({ projectRoot, skillRoot, skillName: 'bmad-testarch-test-design' });
+  const skillRoot = resolveWorkflowSkill({ projectRoot, skillName: 'bmad-tea-test-design', skillRoot: options.skillRoot });
+  const resolvedConfig = resolveTeaConfig({ projectRoot, skillRoot, skillName: 'bmad-tea-test-design' });
   const outputValue =
     options.outputDir || resolvedConfig.configSnapshot.modules.tea.test_artifacts.replaceAll('{project-root}', projectRoot);
   const outputDir = projectPath(projectRoot, outputValue, '--output-dir');

package/cli/test-review.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * tea-test-review — headless runner for the bmad-testarch-test-review skill.
+ * tea-test-review — headless runner for the bmad-tea-test-review skill.
  *
  * Runs the review skill shipped in this package (or, with --project-skill, the
  * copy a consuming project vendored), splits the PR diff into
@@ -582,7 +582,7 @@ async function runReview(session) {
     .name('tea-test-review')
     .version(TEA_CLI_VERSION)
     .description(
-      "Headless runner for the bmad-testarch-test-review skill: scopes the review to the PR's changed test files, reads the rest of the diff as context, and emits a JSON verdict with CI-friendly exit codes. `tea-test-review render --help` renders a verdict into the comment, check-run and summary text.",
+      "Headless runner for the bmad-tea-test-review skill: scopes the review to the PR's changed test files, reads the rest of the diff as context, and emits a JSON verdict with CI-friendly exit codes. `tea-test-review render --help` renders a verdict into the comment, check-run and summary text.",
     )
     .option(
       '--base <ref>',
@@ -1014,7 +1014,7 @@ async function runReview(session) {
     fail(
       EXIT.ENV_ERROR,
       `The TEA knowledge base is not installed beside the skill (expected ${path.resolve(knowledgeIndex)}).\n` +
-        'Install bmod-tea next to bmad-testarch-test-review: npx skills add bmad-code-org/bmad-method-test-architecture-enterprise --skill bmod-tea',
+        'Install bmod-tea next to bmad-tea-test-review: npx skills add bmad-code-org/bmad-method-test-architecture-enterprise --skill bmod-tea',
     );
   }