ma-agents 3.6.2 → 3.8.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-trace/trace-template.md

@@ -4,13 +4,21 @@ lastStep: ''
 lastSaved: ''
 workflowType: 'testarch-trace'
 inputDocuments: []
+coverageBasis: ''
+oracleConfidence: ''
+oracleResolutionMode: ''
+oracleSources: []
+externalPointerStatus: ''
 ---
 
-# Traceability Matrix & Gate Decision - Story {STORY_ID}
+# Traceability Matrix & Gate Decision - {TRACE_TARGET_LABEL}
 
-**Story:** {STORY_TITLE}
+**Target:** {TRACE_TARGET_LABEL}
 **Date:** {DATE}
 **Evaluator:** {user_name or TEA Agent}
+**Coverage Oracle:** {COVERAGE_BASIS}
+**Oracle Confidence:** {ORACLE_CONFIDENCE}
+**Oracle Sources:** {ORACLE_SOURCES}
 
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-trace/workflow-plan.md

@@ -1,21 +1,24 @@
-    # Workflow Plan: testarch-trace
+# Workflow Plan: testarch-trace
 
-    ## Create Mode (steps-c)
-    - step-01-load-context.md
+## Create Mode (steps-c)
 
+- step-01-load-context.md
 - step-02-discover-tests.md
 - step-03-map-criteria.md
 - step-04-analyze-gaps.md
 - step-05-gate-decision.md
 
-  ## Validate Mode (steps-v)
-  - step-01-validate.md
+## Validate Mode (steps-v)
 
-  ## Edit Mode (steps-e)
-  - step-01-assess.md
-  - step-02-apply-edit.md
+- step-01-validate.md
 
-  ## Outputs
-  - {test_artifacts}/traceability-matrix.md
+## Edit Mode (steps-e)
 
-- Gate decision summary (if evidence available)
+- step-01-assess.md
+- step-02-apply-edit.md
+
+## Outputs
+
+- {test_artifacts}/traceability-matrix.md
+- {test_artifacts}/e2e-trace-summary.json
+- {test_artifacts}/gate-decision.json (when gate-eligible)

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-trace/workflow.yaml

@@ -28,9 +28,33 @@ variables:
   coverage_levels: "e2e,api,component,unit" # Which test levels to trace
   gate_type: "story" # story | epic | release | hotfix - determines gate scope
   decision_mode: "deterministic" # deterministic (rule-based) | manual (team decision)
+  collection_mode: "contract_static" # contract_static | inventory_only | runtime_manifest | deferred_shared | waived | restricted | inaccessible
+  allow_gate: true # Emit gate_status and gate-decision.json only when collection is gate-eligible
+  coverage_basis: "auto" # auto | acceptance_criteria | synthetic_requirements | openapi_endpoints | user_journeys; Step 1 must resolve and persist a concrete value before Step 4/5 export
+  summary_confidence: "auto" # auto | high | medium | low; Step 1 must resolve and persist a concrete value before Step 4/5 export
+  allow_external_pointer_resolution: true # Follow local placeholder pointers (e.g., Jira/Confluence) when compatible adapters exist
+  allow_synthetic_oracle: true # Infer journeys/requirements from source when no formal oracle exists
 
 # Output configuration
 default_output_file: "{test_artifacts}/traceability-matrix.md"
+e2e_trace_summary_output: "{test_artifacts}/e2e-trace-summary.json" # Machine-readable summary consumed by CI/CD and reporting pipelines
+gate_decision_output: "{test_artifacts}/gate-decision.json" # Optional downstream gate signal for CI/CD enforcement
+
+# e2e-trace-summary.json schema (emitted by step-05 at workflow completion)
+# schema_version: 1
+# generated_at: ISO timestamp
+# workflow: "bmad-testarch-trace"
+# repo / collection_mode / collection_status / coverage_basis / source_sha
+# target: { type, id, label }
+# gate_status: PASS | CONCERNS | FAIL | WAIVED   (only when allow_gate is true and collection_status is COLLECTED)
+# coverage_statistics: { total_requirements, fully_covered, partially_covered, uncovered, overall_coverage_pct, priority_breakdown{P0..P3}, by_level{e2e,api,component,unit} }
+# tests: { files, cases, skipped_cases, fixme_cases, pending_cases }
+# gap_analysis: { critical_gaps, high_gaps, medium_gaps, low_gaps }
+# heuristics: { endpoint_gaps, auth_negative_path_status, error_path_status }
+# gate_criteria: { p0_coverage_required/actual/status, p1_coverage_target/minimum/actual/status, overall_coverage_minimum/actual/status } (gate-eligible runs only)
+# blockers: [ { id, severity, reason, test_file?, test_title? } ]
+# recommendations: [ { priority, action, requirements[] } ]
+# links: { trace_report_path, trace_report_url, artifact_url }
 
 # Required tools
 required_tools:

package/lib/bmad-cache/tea/test/test-installation-components.js

@@ -99,63 +99,104 @@ async function runTests() {
   try {
     const skillDir = path.join(projectRoot, 'src/agents/bmad-tea');
     const skillMdPath = path.join(skillDir, 'SKILL.md');
-    const manifestPath = path.join(skillDir, 'bmad-skill-manifest.yaml');
+    const customizePath = path.join(skillDir, 'customize.toml');
 
-    // Validate SKILL.md exists and has required sections
+    // Validate SKILL.md matches the new BMM agent activation pattern
     if (await pathExists(skillMdPath)) {
       const skillContent = await fs.readFile(skillMdPath, 'utf8');
 
       assert(skillContent.includes('name: bmad-tea'), 'SKILL.md has correct skill name in frontmatter');
-      assert(skillContent.includes('## Identity'), 'SKILL.md has Identity section');
-      assert(skillContent.includes('## Principles'), 'SKILL.md has Principles section');
-      assert(skillContent.includes('## Critical Actions'), 'SKILL.md has Critical Actions section');
-      assert(skillContent.includes('## Capabilities'), 'SKILL.md has Capabilities section');
       assert(skillContent.includes('## On Activation'), 'SKILL.md has On Activation section');
+      assert(
+        skillContent.includes('{project-root}/_bmad/scripts/resolve_customization.py'),
+        'SKILL.md routes customization through the shared resolver',
+      );
+      assert(skillContent.includes('--key agent'), 'SKILL.md resolves the [agent] customization block');
+      assert(skillContent.includes('{agent.role}'), 'SKILL.md layers {agent.role} onto the persona');
+      assert(skillContent.includes('{agent.identity}'), 'SKILL.md layers {agent.identity} onto the persona');
+      assert(skillContent.includes('{agent.principles}'), 'SKILL.md layers {agent.principles} onto the persona');
+      assert(skillContent.includes('{agent.persistent_facts}'), 'SKILL.md loads {agent.persistent_facts}');
+      assert(skillContent.includes('{agent.menu}'), 'SKILL.md dispatches from {agent.menu}');
+      assert(skillContent.includes('activation_steps_prepend'), 'SKILL.md runs activation_steps_prepend');
+      assert(skillContent.includes('activation_steps_append'), 'SKILL.md runs activation_steps_append');
+      assert(skillContent.includes('## Critical Actions'), 'SKILL.md has Critical Actions section');
 
-      // Verify all 9 capability codes are present in the capabilities table
-      const capabilityCodes = ['TMT', 'TF', 'AT', 'TA', 'TD', 'TR', 'NR', 'CI', 'RV'];
-      for (const code of capabilityCodes) {
-        const codePattern = new RegExp(`\\|\\s*${code}\\s*\\|`);
-        assert(codePattern.test(skillContent), `SKILL.md has capability code ${code}`);
-      }
-
-      // Verify no BMM references
+      // Verify old-pattern artifacts are gone
+      assert(!skillContent.includes('resolve-customization.py'), 'SKILL.md no longer calls the per-skill resolver stub');
+      assert(!skillContent.includes('{persona.displayName}'), 'SKILL.md no longer uses the old {persona.*} namespace');
       assert(!skillContent.includes('_bmad/bmm/'), 'SKILL.md has no _bmad/bmm/ references');
       assert(!skillContent.includes('module: bmm'), 'SKILL.md has no module: bmm references');
     } else {
       assert(false, 'SKILL.md exists', 'src/agents/bmad-tea/SKILL.md not found');
     }
 
-    // Validate bmad-skill-manifest.yaml
-    if (await pathExists(manifestPath)) {
-      const manifest = yaml.load(await fs.readFile(manifestPath, 'utf8'));
-
-      assert(manifest.type === 'agent', 'Manifest has type: agent');
-      assert(manifest.name === 'bmad-tea', 'Manifest has correct name');
-      assert(manifest.module === 'tea', 'Manifest has module: tea');
-      assert(manifest.canonicalId === 'bmad-tea', 'Manifest has correct canonicalId');
-      assert(manifest.webskip === true, 'Manifest has webskip: true');
-      assert(manifest.hasSidecar === false, 'Manifest has hasSidecar: false');
-
-      // Verify all 9 capability skill IDs reference real workflow directories
-      const expectedSkillDirs = [
-        'bmad-teach-me-testing',
-        'bmad-testarch-framework',
-        'bmad-testarch-atdd',
-        'bmad-testarch-automate',
-        'bmad-testarch-test-design',
-        'bmad-testarch-trace',
-        'bmad-testarch-nfr',
-        'bmad-testarch-ci',
-        'bmad-testarch-test-review',
+    // Validate customize.toml carries the agent essence + menu in the new [agent] namespace.
+    // Parse with a tiny line-by-line reader — good enough for flat key/value assertions
+    // without adding a TOML dep.
+    if (await pathExists(customizePath)) {
+      const customizeContent = await fs.readFile(customizePath, 'utf8');
+
+      assert(customizeContent.includes('[agent]'), 'customize.toml has [agent] section');
+      assert(/^\s*name\s*=\s*"Murat"/m.test(customizeContent), 'customize.toml pins agent.name = "Murat"');
+      assert(/^\s*title\s*=\s*"Master Test Architect and Quality Advisor"/m.test(customizeContent), 'customize.toml pins agent.title');
+      assert(/^\s*icon\s*=\s*"🧪"/m.test(customizeContent), 'customize.toml pins agent.icon');
+      assert(customizeContent.includes('persistent_facts'), 'customize.toml defines persistent_facts');
+      assert(
+        customizeContent.includes('file:{project-root}/**/project-context.md'),
+        'customize.toml loads project-context.md as a persistent fact',
+      );
+      assert(customizeContent.includes('activation_steps_prepend'), 'customize.toml defines activation_steps_prepend');
+      assert(customizeContent.includes('activation_steps_append'), 'customize.toml defines activation_steps_append');
+
+      // Verify all 9 capability codes live on the [[agent.menu]] array-of-tables
+      const expectedMenu = [
+        { code: 'TMT', skill: 'bmad-teach-me-testing' },
+        { code: 'TF', skill: 'bmad-testarch-framework' },
+        { code: 'AT', skill: 'bmad-testarch-atdd' },
+        { code: 'TA', skill: 'bmad-testarch-automate' },
+        { code: 'TD', skill: 'bmad-testarch-test-design' },
+        { code: 'TR', skill: 'bmad-testarch-trace' },
+        { code: 'NR', skill: 'bmad-testarch-nfr' },
+        { code: 'CI', skill: 'bmad-testarch-ci' },
+        { code: 'RV', skill: 'bmad-testarch-test-review' },
       ];
-      for (const skillDir of expectedSkillDirs) {
-        const workflowDir = path.join(projectRoot, `src/workflows/testarch/${skillDir}`);
-        assert(await pathExists(workflowDir), `Capability skill ${skillDir} has matching workflow directory`);
+      for (const { code, skill } of expectedMenu) {
+        const codePattern = new RegExp(`\\[\\[agent\\.menu]]\\s*\\ncode\\s*=\\s*"${code}"`);
+        assert(codePattern.test(customizeContent), `customize.toml has [[agent.menu]] entry for code ${code}`);
+        assert(customizeContent.includes(`skill = "${skill}"`), `customize.toml menu ${code} dispatches to ${skill}`);
+        const workflowDir = path.join(projectRoot, `src/workflows/testarch/${skill}`);
+        assert(await pathExists(workflowDir), `Capability skill ${skill} has matching workflow directory`);
       }
     } else {
-      assert(false, 'bmad-skill-manifest.yaml exists', 'src/agents/bmad-tea/bmad-skill-manifest.yaml not found');
+      assert(false, 'customize.toml exists', 'src/agents/bmad-tea/customize.toml not found');
+    }
+
+    // module.yaml must declare the agent essence for the BMM central config roster
+    const moduleYamlPath = path.join(projectRoot, 'src/module.yaml');
+    const moduleYaml = yaml.load(await fs.readFile(moduleYamlPath, 'utf8'));
+    assert(Array.isArray(moduleYaml.agents), 'module.yaml has agents: array');
+    const teaAgentEntry = (moduleYaml.agents || []).find((entry) => entry && entry.code === 'bmad-tea');
+    assert(teaAgentEntry !== undefined, 'module.yaml agents: contains bmad-tea entry');
+    if (teaAgentEntry) {
+      assert(teaAgentEntry.name === 'Murat', 'module.yaml bmad-tea entry has name: Murat');
+      assert(teaAgentEntry.title && teaAgentEntry.title.length > 0, 'module.yaml bmad-tea entry has a title');
+      assert(teaAgentEntry.icon === '🧪', 'module.yaml bmad-tea entry has icon 🧪');
+      assert(teaAgentEntry.team === 'software-development', 'module.yaml bmad-tea entry has team: software-development');
+      assert(
+        typeof teaAgentEntry.description === 'string' && teaAgentEntry.description.length > 0,
+        'module.yaml bmad-tea entry has a description',
+      );
     }
+
+    // Old-pattern files must be gone
+    assert(
+      !(await pathExists(path.join(skillDir, 'bmad-skill-manifest.yaml'))),
+      'Legacy bmad-skill-manifest.yaml is removed from the agent',
+    );
+    assert(
+      !(await pathExists(path.join(skillDir, 'scripts', 'resolve-customization.py'))),
+      'Legacy per-agent resolve-customization.py is removed',
+    );
   } catch (error) {
     assert(false, 'TEA agent native skill structure validates', error.message);
   }
@@ -169,12 +210,18 @@ async function runTests() {
 
   try {
     const teaIndexPath = path.join(projectRoot, 'src/agents/bmad-tea/resources/tea-index.csv');
+    const knowledgeDir = path.join(projectRoot, 'src/agents/bmad-tea/resources/knowledge');
 
     if (await pathExists(teaIndexPath)) {
       const csvContent = await fs.readFile(teaIndexPath, 'utf8');
-      const lines = csvContent.trim().split('\n');
-
-      assert(lines.length === 43, 'tea-index.csv has 43 lines (header + 42 fragments)', `Found ${lines.length} lines`);
+      const lines = csvContent.trim().split(/\r?\n/);
+      const knowledgeFiles = (await fs.readdir(knowledgeDir)).filter((fileName) => fileName.endsWith('.md'));
+
+      assert(
+        lines.length === knowledgeFiles.length + 1,
+        'tea-index.csv line count matches knowledge fragments',
+        `Found ${lines.length} lines for ${knowledgeFiles.length} knowledge fragments`,
+      );
       assert(lines[0].includes('id,name,description,tags,tier,fragment_file'), 'tea-index.csv has correct header format');
 
       // Verify no BMM references in CSV
@@ -193,32 +240,72 @@ async function runTests() {
   // ============================================================
   console.log(`${colors.yellow}Test Suite 4: Workflow Structure${colors.reset}\n`);
 
-  const teachMeWorkflowPath = path.join(projectRoot, 'src/workflows/testarch/bmad-teach-me-testing/workflow.md');
-  try {
-    if (await pathExists(teachMeWorkflowPath)) {
-      const teachMeContent = await fs.readFile(teachMeWorkflowPath, 'utf8');
-      assert(teachMeContent.length > 0, 'bmad-teach-me-testing/workflow.md exists');
-      assert(!teachMeContent.includes('_bmad/bmm/'), 'bmad-teach-me-testing has no _bmad/bmm/ references');
+  const workflowDirs = [
+    'bmad-teach-me-testing',
+    'bmad-testarch-framework',
+    'bmad-testarch-ci',
+    'bmad-testarch-test-design',
+    'bmad-testarch-atdd',
+    'bmad-testarch-automate',
+    'bmad-testarch-test-review',
+    'bmad-testarch-nfr',
+    'bmad-testarch-trace',
+  ];
+
+  for (const dirName of workflowDirs) {
+    const skillMdPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/SKILL.md`);
+    const customizeTomlPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/customize.toml`);
+    const workflowYamlPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/workflow.yaml`);
+    const instructionsMdPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/instructions.md`);
+
+    if (await pathExists(skillMdPath)) {
+      try {
+        const skillContent = await fs.readFile(skillMdPath, 'utf8');
+        assert(skillContent && skillContent.trim().length > 0, `${dirName}/SKILL.md is not empty`);
+        assert(skillContent.includes('## On Activation'), `${dirName}/SKILL.md has On Activation section`);
+        assert(
+          skillContent.includes('resolve_customization.py --skill {skill-root} --key workflow'),
+          `${dirName}/SKILL.md resolves the workflow customization block`,
+        );
+        assert(skillContent.includes('{workflow.activation_steps_prepend}'), `${dirName}/SKILL.md executes prepend activation steps`);
+        assert(skillContent.includes('{workflow.activation_steps_append}'), `${dirName}/SKILL.md executes append activation steps`);
+        assert(skillContent.includes('{workflow.persistent_facts}'), `${dirName}/SKILL.md loads persistent facts`);
+        assert(
+          skillContent.includes('Resolve sibling workflow files such as `instructions.md`'),
+          `${dirName}/SKILL.md explains sibling workflow path resolution`,
+        );
+        assert(/\{skill-root\}\/steps-[cev]\//.test(skillContent), `${dirName}/SKILL.md routes first step from {skill-root}`);
+        assert(!skillContent.includes('Read `{skill-root}/workflow.md`'), `${dirName}/SKILL.md no longer redirects to workflow.md`);
+        assert(!skillContent.includes('[workflow.md](workflow.md)'), `${dirName}/SKILL.md no longer uses a bare relative workflow link`);
+      } catch (error) {
+        assert(false, `${dirName}/SKILL.md validates`, error.message);
+      }
     } else {
-      assert(false, 'bmad-teach-me-testing workflow exists', 'src/workflows/testarch/bmad-teach-me-testing/workflow.md not found');
+      assert(false, `${dirName}/SKILL.md exists`, `src/workflows/testarch/${dirName}/SKILL.md not found`);
     }
-  } catch (error) {
-    assert(false, 'teach-me-testing workflow validates', error.message);
-  }
 
-  const workflowDirs = {
-    'bmad-testarch-framework': 'framework',
-    'bmad-testarch-ci': 'ci',
-    'bmad-testarch-test-design': 'test-design',
-    'bmad-testarch-atdd': 'atdd',
-    'bmad-testarch-automate': 'automate',
-    'bmad-testarch-test-review': 'test-review',
-    'bmad-testarch-nfr': 'nfr-assess',
-    'bmad-testarch-trace': 'trace',
-  };
-
-  for (const [dirName, displayName] of Object.entries(workflowDirs)) {
-    const workflowYamlPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/workflow.yaml`);
+    if (await pathExists(customizeTomlPath)) {
+      try {
+        const customizeContent = await fs.readFile(customizeTomlPath, 'utf8');
+        assert(customizeContent.includes('[workflow]'), `${dirName}/customize.toml has [workflow] section`);
+        assert(customizeContent.includes('activation_steps_prepend'), `${dirName}/customize.toml defines activation_steps_prepend`);
+        assert(customizeContent.includes('activation_steps_append'), `${dirName}/customize.toml defines activation_steps_append`);
+        assert(customizeContent.includes('persistent_facts'), `${dirName}/customize.toml defines persistent_facts`);
+        assert(customizeContent.includes('on_complete'), `${dirName}/customize.toml defines on_complete`);
+        assert(
+          customizeContent.includes('file:{project-root}/**/project-context.md'),
+          `${dirName}/customize.toml loads project-context.md as a persistent fact`,
+        );
+      } catch (error) {
+        assert(false, `${dirName}/customize.toml validates`, error.message);
+      }
+    } else {
+      assert(false, `${dirName}/customize.toml exists`, `src/workflows/testarch/${dirName}/customize.toml not found`);
+    }
+
+    // workflow.md was folded into SKILL.md and removed (PR: workflow customization rollout).
+    const legacyWorkflowMdPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/workflow.md`);
+    assert(!(await pathExists(legacyWorkflowMdPath)), `${dirName}/workflow.md is removed (content lives in SKILL.md)`);
 
     if (await pathExists(workflowYamlPath)) {
       try {
@@ -232,6 +319,63 @@ async function runTests() {
         assert(false, `${dirName}/workflow.yaml validates`, error.message);
       }
     }
+
+    if (await pathExists(instructionsMdPath)) {
+      try {
+        const instructionsContent = await fs.readFile(instructionsMdPath, 'utf8');
+        assert(!instructionsContent.includes('`./steps-'), `${dirName}/instructions.md has no bare relative step references`);
+        assert(
+          instructionsContent.includes('`{skill-root}/steps-c/') ||
+            instructionsContent.includes('`{skill-root}/steps-v/') ||
+            instructionsContent.includes('`{skill-root}/steps-e/'),
+          `${dirName}/instructions.md anchors step entrypoints to {skill-root}`,
+        );
+      } catch (error) {
+        assert(false, `${dirName}/instructions.md validates`, error.message);
+      }
+    }
+
+    for (const stepDir of ['steps-c', 'steps-e', 'steps-v']) {
+      const stepDirPath = path.join(projectRoot, `src/workflows/testarch/${dirName}/${stepDir}`);
+      if (!(await pathExists(stepDirPath))) continue;
+
+      const stepFiles = (await fs.readdir(stepDirPath)).filter((fileName) => fileName.endsWith('.md'));
+      for (const fileName of stepFiles) {
+        const stepPath = path.join(stepDirPath, fileName);
+        try {
+          const stepContent = await fs.readFile(stepPath, 'utf8');
+          const stepLabel = `${dirName}/${stepDir}/${fileName}`;
+
+          assert(!stepContent.includes("nextStepFile: './"), `${stepLabel} has no cwd-sensitive nextStepFile`);
+          if (stepContent.includes('nextStepFile:')) {
+            assert(/nextStepFile: '\{skill-root\}\/steps-[cev]\//.test(stepContent), `${stepLabel} anchors nextStepFile to {skill-root}`);
+          }
+
+          assert(!stepContent.includes("validationChecklist: '../checklist.md'"), `${stepLabel} has no relative validation checklist path`);
+          if (stepContent.includes('validationChecklist:')) {
+            assert(
+              stepContent.includes("validationChecklist: '{skill-root}/checklist.md'"),
+              `${stepLabel} anchors validationChecklist to {skill-root}`,
+            );
+          }
+
+          assert(!stepContent.includes("checklistFile: '../checklist.md'"), `${stepLabel} has no relative checklistFile path`);
+          if (stepContent.includes('checklistFile:')) {
+            assert(
+              stepContent.includes("checklistFile: '{skill-root}/checklist.md'"),
+              `${stepLabel} anchors checklistFile to {skill-root}`,
+            );
+          }
+
+          assert(!stepContent.includes("workflowPath: '../'"), `${stepLabel} has no relative workflowPath`);
+          if (stepContent.includes('workflowPath:')) {
+            assert(stepContent.includes("workflowPath: '{skill-root}'"), `${stepLabel} anchors workflowPath to {skill-root}`);
+          }
+        } catch (error) {
+          assert(false, `${dirName}/${stepDir}/${fileName} validates`, error.message);
+        }
+      }
+    }
   }
 
   const frameworkScaffoldStepPath = path.join(

package/lib/bmad-cache/tea/test/test-knowledge-base.js

@@ -88,7 +88,12 @@ function runTests() {
     const csv = fs.readFileSync(indexPath, 'utf8');
     records = parse(csv, { columns: true, skip_empty_lines: true });
 
-    assert(records.length === 42, 'tea-index.csv has 42 fragment records', `Found ${records.length}`);
+    const expectedFragmentCount = fs.readdirSync(path.join(kbRoot, 'knowledge')).filter((f) => f.endsWith('.md')).length;
+    assert(
+      records.length === expectedFragmentCount,
+      `tea-index.csv has ${expectedFragmentCount} fragment records`,
+      `Found ${records.length}`,
+    );
 
     const requiredFields = ['id', 'name', 'description', 'tags', 'tier', 'fragment_file'];
     const missingFields = requiredFields.filter((field) => !Object.prototype.hasOwnProperty.call(records[0] || {}, field));

package/lib/bmad-cache/tea/test/test-release-metadata.js

@@ -0,0 +1,71 @@
+/**
+ * Release metadata validation for publishable builds.
+ *
+ * Verifies:
+ * - package.json, package-lock.json, and marketplace.json share the same version
+ * - the package is not marked private
+ * - publishConfig.access remains public
+ *
+ * Usage: node test/test-release-metadata.js
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const projectRoot = path.join(__dirname, '..');
+const packageJsonPath = path.join(projectRoot, 'package.json');
+const packageLockPath = path.join(projectRoot, 'package-lock.json');
+const marketplacePath = path.join(projectRoot, '.claude-plugin', 'marketplace.json');
+
+function readJson(filePath, label) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    console.error(`Release metadata validation failed: unable to read ${label} at ${filePath}`);
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+const packageJson = readJson(packageJsonPath, 'package.json');
+const packageLock = readJson(packageLockPath, 'package-lock.json');
+const marketplace = readJson(marketplacePath, '.claude-plugin/marketplace.json');
+const marketplacePlugin = (marketplace.plugins || []).find((plugin) => plugin && plugin.name === packageJson.name);
+
+const errors = [];
+
+if (packageJson.private === true) {
+  errors.push('package.json must not set "private": true when publishing to npm.');
+}
+
+if (packageJson.publishConfig?.access !== 'public') {
+  errors.push('package.json must set publishConfig.access to "public".');
+}
+
+if (packageLock.version !== packageJson.version) {
+  errors.push(`package-lock.json version ${packageLock.version} does not match package.json version ${packageJson.version}.`);
+}
+
+if (packageLock.packages?.['']?.version !== packageJson.version) {
+  errors.push(
+    `package-lock.json root package version ${packageLock.packages?.['']?.version} does not match package.json version ${packageJson.version}.`,
+  );
+}
+
+if (!marketplacePlugin) {
+  errors.push(`.claude-plugin/marketplace.json is missing the plugin entry for ${packageJson.name}.`);
+} else if (marketplacePlugin.version !== packageJson.version) {
+  errors.push(
+    `.claude-plugin/marketplace.json version ${marketplacePlugin.version} does not match package.json version ${packageJson.version}.`,
+  );
+}
+
+if (errors.length > 0) {
+  console.error('Release metadata validation failed:\n');
+  for (const error of errors) {
+    console.error(`- ${error}`);
+  }
+  process.exit(1);
+}
+
+console.log(`Release metadata is synchronized and publishable for v${packageJson.version}.`);

package/lib/bmad-cache/tea/tools/validate-agent-schema.js

@@ -4,6 +4,8 @@
  * Scans for agent definitions in src/agents/:
  * - Legacy format: *.agent.yaml (validated against Zod schema)
  * - Native skill format: {name}/bmad-skill-manifest.yaml + SKILL.md
+ * - BMM native format: {name}/customize.toml + SKILL.md, with the agent's
+ *   essence declared under the top-level agents: array in src/module.yaml
  *
  * Usage: node tools/validate-agent-schema.js [project_root]
  * Exit codes: 0 = success, 1 = validation failures
@@ -41,6 +43,77 @@ async function main(customProjectRoot) {
     absolute: true,
   });
 
+  // BMM-native agents: customize.toml + SKILL.md, with essence in module.yaml agents: array
+  const bmmAgents = await glob('src/agents/*/customize.toml', {
+    cwd: project_root,
+    absolute: true,
+  });
+
+  // If no legacy agents and no manifest-style agents, fall through to BMM-native validation
+  if (agentFiles.length === 0 && skillManifests.length === 0 && bmmAgents.length > 0) {
+    console.log(`Found ${bmmAgents.length} BMM-native agent(s) (customize.toml + SKILL.md + module.yaml agents:)\n`);
+
+    const moduleYamlPath = path.join(project_root, 'src/module.yaml');
+    let moduleAgents = [];
+    if (fs.existsSync(moduleYamlPath)) {
+      try {
+        const parsed = yaml.parse(fs.readFileSync(moduleYamlPath, 'utf8'));
+        if (parsed && Array.isArray(parsed.agents)) moduleAgents = parsed.agents;
+      } catch (error) {
+        console.log(`❌ Failed to parse src/module.yaml: ${error.message}`);
+        process.exit(1);
+      }
+    }
+
+    const bmmErrors = [];
+    for (const customizePath of bmmAgents) {
+      const relativePath = path.relative(process.cwd(), customizePath);
+      const agentDir = path.dirname(customizePath);
+      const agentCode = path.basename(agentDir);
+      const issues = [];
+
+      if (!fs.existsSync(path.join(agentDir, 'SKILL.md'))) {
+        issues.push({ message: 'Missing SKILL.md file alongside customize.toml' });
+      }
+
+      const customizeRaw = fs.readFileSync(customizePath, 'utf8');
+      if (!customizeRaw.includes('[agent]')) {
+        issues.push({ message: 'customize.toml must declare an [agent] section' });
+      }
+
+      const rosterEntry = moduleAgents.find((entry) => entry && entry.code === agentCode);
+      if (rosterEntry) {
+        const requiredRosterFields = ['name', 'title', 'icon', 'description', 'team'];
+        const missing = requiredRosterFields.filter((f) => !rosterEntry[f]);
+        if (missing.length > 0) {
+          issues.push({ message: `src/module.yaml agents: entry for "${agentCode}" missing fields: ${missing.join(', ')}` });
+        }
+      } else {
+        issues.push({
+          message: `No matching entry in src/module.yaml agents: for code "${agentCode}" — the BMM central config roster won't pick this agent up on install`,
+        });
+      }
+
+      if (issues.length > 0) {
+        bmmErrors.push({ file: relativePath, issues });
+      } else {
+        console.log(`✅ ${relativePath}`);
+      }
+    }
+
+    if (bmmErrors.length > 0) {
+      console.log('\n❌ Validation failed:\n');
+      for (const { file, issues } of bmmErrors) {
+        console.log(`\n📄 ${file}`);
+        for (const issue of issues) console.log(`   Error: ${issue.message}`);
+      }
+      process.exit(1);
+    }
+
+    console.log(`\n✨ All ${bmmAgents.length} BMM-native agent(s) passed validation!\n`);
+    process.exit(0);
+  }
+
   // If no legacy agents found, validate native skills or fail
   if (agentFiles.length === 0) {
     if (skillManifests.length > 0) {

package/lib/bmad-customize/bmm-qa.customize.yaml

@@ -16,7 +16,7 @@ persona:
     - "Evidence matters more than opinions."
 
 menu:
-  - trigger: skill:bmad-ma-agent-sqa
+  - trigger: skill:ma-agent-sqa
     description: "Activate Gad — Software Quality Assurance Expert"
 
 critical_actions: