ma-agents 2.22.1 → 3.0.0

package/lib/bmad-cache/bmb/{src/skills → skills}/bmad-workflow-builder/scripts/scan-path-standards.py

@@ -1,12 +1,15 @@
 #!/usr/bin/env python3
 """Deterministic path standards scanner for BMad skills.
 
-Validates all .md files against BMad path conventions:
+Validates all .md and .json files against BMad path conventions:
 1. {project-root} only valid before /_bmad
 2. Bare _bmad references must have {project-root} prefix
 3. Config variables used directly (no double-prefix)
-4. No ./ or ../ relative prefixes
-5. No absolute paths
+4. Skill-internal paths must use ./ prefix (references/, scripts/, assets/)
+5. No ../ parent directory references
+6. No absolute paths
+7. Frontmatter allows only name and description
+8. No .md files at skill root except SKILL.md
 """
 
 # /// script
@@ -32,13 +35,18 @@ BARE_BMAD_RE = re.compile(r'(?<!\{project-root\}/)_bmad[/\s]')
 # Absolute paths
 ABSOLUTE_PATH_RE = re.compile(r'(?:^|[\s"`\'(])(/(?:Users|home|opt|var|tmp|etc|usr)/\S+)', re.MULTILINE)
 HOME_PATH_RE = re.compile(r'(?:^|[\s"`\'(])(~/\S+)', re.MULTILINE)
-# Relative prefixes
+# Parent directory reference (still invalid)
 RELATIVE_DOT_RE = re.compile(r'(?:^|[\s"`\'(])(\.\./\S+)', re.MULTILINE)
-RELATIVE_DOTSLASH_RE = re.compile(r'(?:^|[\s"`\'(])(\./\S+)', re.MULTILINE)
+# Bare skill-internal paths without ./ prefix
+# Match references/, scripts/, assets/ when NOT preceded by ./
+BARE_INTERNAL_RE = re.compile(r'(?:^|[\s"`\'(])(?<!\./)((?:references|scripts|assets)/\S+)', re.MULTILINE)
 
 # Fenced code block detection (to skip examples showing wrong patterns)
 FENCE_RE = re.compile(r'^```', re.MULTILINE)
 
+# Valid frontmatter keys
+VALID_FRONTMATTER_KEYS = {'name', 'description'}
+
 
 def is_in_fenced_block(content: str, pos: int) -> bool:
     """Check if a position is inside a fenced code block."""
@@ -52,6 +60,76 @@ def get_line_number(content: str, pos: int) -> int:
     return content[:pos].count('\n') + 1
 
 
+def check_frontmatter(content: str, filepath: Path) -> list[dict]:
+    """Validate SKILL.md frontmatter contains only allowed keys."""
+    findings = []
+    if filepath.name != 'SKILL.md':
+        return findings
+
+    if not content.startswith('---'):
+        findings.append({
+            'file': filepath.name,
+            'line': 1,
+            'severity': 'critical',
+            'category': 'frontmatter',
+            'title': 'SKILL.md missing frontmatter block',
+            'detail': 'SKILL.md must start with --- frontmatter containing name and description',
+            'action': 'Add frontmatter with name and description fields',
+        })
+        return findings
+
+    # Find closing ---
+    end = content.find('\n---', 3)
+    if end == -1:
+        findings.append({
+            'file': filepath.name,
+            'line': 1,
+            'severity': 'critical',
+            'category': 'frontmatter',
+            'title': 'SKILL.md frontmatter block not closed',
+            'detail': 'Missing closing --- for frontmatter',
+            'action': 'Add closing --- after frontmatter fields',
+        })
+        return findings
+
+    frontmatter = content[4:end]
+    for i, line in enumerate(frontmatter.split('\n'), start=2):
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+        if ':' in line:
+            key = line.split(':', 1)[0].strip()
+            if key not in VALID_FRONTMATTER_KEYS:
+                findings.append({
+                    'file': filepath.name,
+                    'line': i,
+                    'severity': 'high',
+                    'category': 'frontmatter',
+                    'title': f'Invalid frontmatter key: {key}',
+                    'detail': f'Only {", ".join(sorted(VALID_FRONTMATTER_KEYS))} are allowed in frontmatter',
+                    'action': f'Remove {key} from frontmatter — use as content field in SKILL.md body instead',
+                })
+
+    return findings
+
+
+def check_root_md_files(skill_path: Path) -> list[dict]:
+    """Check that no .md files exist at skill root except SKILL.md."""
+    findings = []
+    for md_file in skill_path.glob('*.md'):
+        if md_file.name != 'SKILL.md':
+            findings.append({
+                'file': md_file.name,
+                'line': 0,
+                'severity': 'high',
+                'category': 'structure',
+                'title': f'Prompt file at skill root: {md_file.name}',
+                'detail': 'All progressive disclosure content must be in ./references/ — only SKILL.md belongs at root',
+                'action': f'Move {md_file.name} to references/{md_file.name}',
+            })
+    return findings
+
+
 def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
     """Scan a single file for path standard violations."""
     findings = []
@@ -65,10 +143,10 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
          'Absolute path found — not portable across machines'),
         (HOME_PATH_RE, 'absolute-path', 'high',
          'Home directory path (~/) found — environment-specific'),
-        (RELATIVE_DOT_RE, 'relative-prefix', 'medium',
+        (RELATIVE_DOT_RE, 'relative-prefix', 'high',
          'Parent directory reference (../) found — fragile, breaks with reorganization'),
-        (RELATIVE_DOTSLASH_RE, 'relative-prefix', 'medium',
-         'Relative prefix (./) found — breaks when execution directory changes'),
+        (BARE_INTERNAL_RE, 'bare-internal-path', 'high',
+         'Bare skill-internal path without ./ prefix — use ./references/, ./scripts/, ./assets/ to distinguish from {project-root} paths'),
     ]
 
     for pattern, category, severity, message in checks:
@@ -94,9 +172,6 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
         pos = match.start()
         if skip_fenced and is_in_fenced_block(content, pos):
             continue
-        # Check that this isn't part of {project-root}/_bmad
-        # The negative lookbehind handles this, but double-check
-        # the broader context
         start = max(0, pos - 30)
         before = content[start:pos]
         if '{project-root}/' in before:
@@ -117,13 +192,22 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
 
 
 def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
-    """Scan all .md files in a skill directory."""
+    """Scan all .md and .json files in a skill directory."""
     all_findings = []
 
-    # Find all .md files
-    md_files = sorted(skill_path.rglob('*.md'))
+    # Check for .md files at root that aren't SKILL.md
+    all_findings.extend(check_root_md_files(skill_path))
+
+    # Check SKILL.md frontmatter
+    skill_md = skill_path / 'SKILL.md'
+    if skill_md.exists():
+        content = skill_md.read_text(encoding='utf-8')
+        all_findings.extend(check_frontmatter(content, skill_md))
+
+    # Find all .md and .json files
+    md_files = sorted(list(skill_path.rglob('*.md')) + list(skill_path.rglob('*.json')))
     if not md_files:
-        print(f"Warning: No .md files found in {skill_path}", file=sys.stderr)
+        print(f"Warning: No .md or .json files found in {skill_path}", file=sys.stderr)
 
     files_scanned = []
     for md_file in md_files:
@@ -142,6 +226,9 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
         'double_prefix': 0,
         'absolute_path': 0,
         'relative_prefix': 0,
+        'bare_internal_path': 0,
+        'frontmatter': 0,
+        'structure': 0,
     }
 
     for f in all_findings:
@@ -155,7 +242,7 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     return {
         'scanner': 'path-standards',
         'script': 'scan-path-standards.py',
-        'version': '1.0.0',
+        'version': '2.0.0',
         'skill_path': str(skill_path),
         'timestamp': datetime.now(timezone.utc).isoformat(),
         'files_scanned': files_scanned,

package/lib/bmad-cache/bmb/skills/module-help.csv

@@ -0,0 +1,6 @@
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+BMad Builder,bmad-builder-setup,Setup Builder Module,SB,"Install or update BMad Builder module config and help entries. Collects user preferences, writes config.yaml, and migrates legacy configs.",configure,,anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml
+BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, convert, or fix an agent skill.",build-process,"[-H] [description | path]",anytime,,bmad-agent-builder:quality-optimizer,false,output_folder,agent skill
+BMad Builder,bmad-agent-builder,Optimize an Agent,OA,Validate and optimize an existing agent skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report
+BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, convert, or fix a workflow or utility skill.",build-process,"[-H] [description | path]",anytime,,bmad-workflow-builder:quality-optimizer,false,output_folder,workflow skill
+BMad Builder,bmad-workflow-builder,Optimize a Workflow,OW,Validate and optimize an existing workflow or utility skill. Produces a quality report.,quality-optimizer,[-H] [path],anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report

package/lib/bmad-cache/bmb/skills/module.yaml

@@ -0,0 +1,20 @@
+code: bmb
+name: "BMad Builder"
+description: "Standard Skill Compliant Factory for BMad Agents, Workflows and Modules"
+module_version: 1.0.0
+default_selected: false
+module_greeting: >
+  Enjoy making your dream creations with the BMad Builder Module!
+  Run this again at any time if you want to reconfigure a setting or have updated the module, (or optionally just update _bmad/config.yaml and config.user.yaml to change existing values)
+
+  For questions, suggestions and support - check us on Discord at https://discord.gg/gk8jAdXWmj
+
+bmad_builder_output_folder:
+  prompt: "Where should your custom output (agent, workflow, module config) be saved?"
+  default: "{project-root}/skills"
+  result: "{project-root}/{value}"
+
+bmad_builder_reports:
+  prompt: "Output for Evals, Test, Quality and Planning Reports?"
+  default: "{project-root}/skills/reports"
+  result: "{project-root}/{value}"

package/lib/bmad-cache/bmb/tools/validate-doc-links.cjs

@@ -0,0 +1,407 @@
+/**
+ * Documentation Link Validator
+ *
+ * Validates site-relative links in markdown files and attempts to fix broken ones.
+ *
+ * What it checks:
+ * - All site-relative links (starting with /) point to existing .md files
+ * - Anchor links (#section) point to valid headings
+ *
+ * What it fixes:
+ * - Broken links where the target file can be found elsewhere in /docs
+ *
+ * Usage:
+ *   node tools/validate-doc-links.js           # Dry run (validate and show issues)
+ *   node tools/validate-doc-links.js --write   # Fix auto-fixable issues
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_ROOT = path.resolve(__dirname, '../docs');
+const DRY_RUN = !process.argv.includes('--write');
+
+// Regex to match markdown links with site-relative paths or bare .md references
+const LINK_REGEX = /\[([^\]]*)\]\(((?:\.{1,2}\/|\/)[^)]+|[\w][^)\s]*\.md(?:[?#][^)]*)?)\)/g;
+
+// File extensions that are static assets, not markdown docs
+const STATIC_ASSET_EXTENSIONS = ['.zip', '.txt', '.pdf', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico'];
+
+// Custom Astro page routes (not part of the docs content collection)
+const CUSTOM_PAGE_ROUTES = new Set([]);
+
+// Regex to extract headings for anchor validation
+const HEADING_PATTERN = /^#{1,6}\s+(.+)$/gm;
+
+/**
+ * Get all markdown files in docs directory, excluding _* directories/files
+ */
+function getMarkdownFiles(dir) {
+  const files = [];
+
+  function walk(currentDir) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.name.startsWith('_')) {
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.mdx'))) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(dir);
+  return files;
+}
+
+/**
+ * Strip fenced code blocks from content
+ */
+function stripCodeBlocks(content) {
+  return content.replaceAll(/```[\s\S]*?```/g, '');
+}
+
+/**
+ * Convert a heading to its anchor slug
+ */
+function headingToAnchor(heading) {
+  return heading
+    .toLowerCase()
+    .replaceAll(/[\u{1F300}-\u{1F9FF}]/gu, '') // Remove emojis
+    .replaceAll(/[^\w\s-]/g, '') // Remove special chars
+    .replaceAll(/\s+/g, '-') // Spaces to hyphens
+    .replaceAll(/-+/g, '-') // Collapse hyphens
+    .replaceAll(/^-+|-+$/g, ''); // Trim hyphens
+}
+
+/**
+ * Extract anchor slugs from a markdown file
+ */
+function extractAnchors(content) {
+  const anchors = new Set();
+  let match;
+
+  HEADING_PATTERN.lastIndex = 0;
+  while ((match = HEADING_PATTERN.exec(content)) !== null) {
+    const headingText = match[1]
+      .trim()
+      .replaceAll(/`[^`]+`/g, '')
+      .replaceAll(/\*\*([^*]+)\*\*/g, '$1')
+      .replaceAll(/\*([^*]+)\*/g, '$1')
+      .replaceAll(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+      .trim();
+    anchors.add(headingToAnchor(headingText));
+  }
+
+  return anchors;
+}
+
+/**
+ * Resolve a site-relative link to a file path
+ * /docs/how-to/installation/install-bmad.md -> docs/how-to/installation/install-bmad.md
+ * /how-to/installation/install-bmad/ -> docs/how-to/installation/install-bmad.md or .../index.md
+ */
+function resolveLink(siteRelativePath, sourceFile) {
+  // Strip anchor and query
+  let checkPath = siteRelativePath.split('#')[0].split('?')[0];
+
+  // Handle relative paths (including bare .md): resolve from source file's directory
+  if (checkPath.startsWith('./') || checkPath.startsWith('../') || (!checkPath.startsWith('/') && checkPath.endsWith('.md'))) {
+    const sourceDir = path.dirname(sourceFile);
+    const resolved = path.resolve(sourceDir, checkPath);
+    // Ensure the resolved path stays within DOCS_ROOT
+    if (!resolved.startsWith(DOCS_ROOT + path.sep) && resolved !== DOCS_ROOT) return null;
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) return resolved;
+    if (fs.existsSync(resolved + '.md')) return resolved + '.md';
+    if (fs.existsSync(resolved + '.mdx')) return resolved + '.mdx';
+    // Directory: check for index.md or index.mdx
+    if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+      const indexFile = path.join(resolved, 'index.md');
+      const indexMdxFile = path.join(resolved, 'index.mdx');
+      if (fs.existsSync(indexFile)) return indexFile;
+      if (fs.existsSync(indexMdxFile)) return indexMdxFile;
+    }
+    return null;
+  }
+
+  // Strip /docs/ prefix if present (legacy absolute links)
+  if (checkPath.startsWith('/docs/')) {
+    checkPath = checkPath.slice(5); // Remove '/docs' but keep leading '/'
+  }
+
+  if (checkPath.endsWith('/')) {
+    // Could be file.md, file.mdx, or directory/index.md/mdx
+    const baseName = checkPath.slice(0, -1);
+    const asMd = path.join(DOCS_ROOT, baseName + '.md');
+    const asMdx = path.join(DOCS_ROOT, baseName + '.mdx');
+    const asIndex = path.join(DOCS_ROOT, checkPath, 'index.md');
+    const asIndexMdx = path.join(DOCS_ROOT, checkPath, 'index.mdx');
+
+    if (fs.existsSync(asMd)) return asMd;
+    if (fs.existsSync(asMdx)) return asMdx;
+    if (fs.existsSync(asIndex)) return asIndex;
+    if (fs.existsSync(asIndexMdx)) return asIndexMdx;
+    return null;
+  }
+
+  // Direct path (e.g., /path/file.md)
+  const direct = path.join(DOCS_ROOT, checkPath);
+  if (fs.existsSync(direct) && fs.statSync(direct).isFile()) return direct;
+
+  // Try with .md extension
+  const withMd = direct + '.md';
+  if (fs.existsSync(withMd)) return withMd;
+
+  // Try with .mdx extension
+  const withMdx = direct + '.mdx';
+  if (fs.existsSync(withMdx)) return withMdx;
+
+  // Directory without trailing slash: check for index.md or index.mdx
+  if (fs.existsSync(direct) && fs.statSync(direct).isDirectory()) {
+    const indexFile = path.join(direct, 'index.md');
+    const indexMdxFile = path.join(direct, 'index.mdx');
+    if (fs.existsSync(indexFile)) return indexFile;
+    if (fs.existsSync(indexMdxFile)) return indexMdxFile;
+  }
+
+  return null;
+}
+
+/**
+ * Search for a file with directory context
+ */
+function findFileWithContext(brokenPath) {
+  // Extract filename and parent directory from the broken path
+  // e.g., /tutorials/getting-started/foo/ -> parent: getting-started, file: foo.md
+  const cleanPath = brokenPath.replace(/\/$/, '').replace(/^(\.\.\/|\.\/|\/)+/, '');
+  const parts = cleanPath.split('/');
+  const fileName = parts.at(-1) + '.md';
+  const parentDir = parts.length > 1 ? parts.at(-2) : null;
+
+  const allFiles = getMarkdownFiles(DOCS_ROOT);
+  const matches = [];
+
+  for (const file of allFiles) {
+    const fileBaseName = path.basename(file);
+    const fileParentDir = path.basename(path.dirname(file));
+
+    // Exact filename match with parent directory context
+    if (fileBaseName === fileName) {
+      if (parentDir && fileParentDir === parentDir) {
+        // Strong match: both filename and parent dir match
+        return [file];
+      }
+      matches.push(file);
+    }
+
+    // Also check for index.md in a matching directory
+    if (fileBaseName === 'index.md' && fileParentDir === fileName.replace('.md', '')) {
+      matches.push(file);
+    }
+  }
+
+  return matches;
+}
+
+/**
+ * Convert absolute file path to site-relative URL
+ */
+function fileToSiteRelative(filePath) {
+  let relative = '/' + path.relative(DOCS_ROOT, filePath);
+  relative = relative.split(path.sep).join('/');
+
+  if (relative.endsWith('/index.md')) {
+    return relative.replace(/\/index\.md$/, '/');
+  }
+  return relative.replace(/\.md$/, '/');
+}
+
+/**
+ * Process a single file and find issues
+ */
+function processFile(filePath) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const strippedContent = stripCodeBlocks(content);
+  const issues = [];
+
+  let match;
+  LINK_REGEX.lastIndex = 0;
+
+  while ((match = LINK_REGEX.exec(strippedContent)) !== null) {
+    const linkText = match[1];
+    const href = match[2];
+
+    // Extract path and anchor
+    const hashIndex = href.indexOf('#');
+    const linkPath = hashIndex === -1 ? href : href.slice(0, hashIndex);
+    const anchor = hashIndex === -1 ? null : href.slice(hashIndex + 1);
+
+    // Skip static asset links (zip, txt, images, etc.)
+    const linkLower = linkPath.toLowerCase();
+    if (STATIC_ASSET_EXTENSIONS.some((ext) => linkLower.endsWith(ext))) {
+      continue;
+    }
+
+    // Skip custom Astro page routes
+    if (CUSTOM_PAGE_ROUTES.has(linkPath)) {
+      continue;
+    }
+
+    // Validate the link target exists
+    const targetFile = resolveLink(linkPath, filePath);
+
+    if (!targetFile) {
+      // Link is broken - try to find the file
+      const candidates = findFileWithContext(linkPath);
+
+      const issue = {
+        type: 'broken-link',
+        linkText,
+        href,
+        linkPath,
+        fullMatch: match[0],
+      };
+
+      if (candidates.length === 1) {
+        issue.status = 'auto-fixable';
+        issue.suggestedFix = fileToSiteRelative(candidates[0]) + (anchor ? '#' + anchor : '');
+        issue.foundAt = path.relative(DOCS_ROOT, candidates[0]);
+      } else if (candidates.length > 1) {
+        issue.status = 'needs-review';
+        issue.candidates = candidates.map((c) => path.relative(DOCS_ROOT, c));
+      } else {
+        issue.status = 'manual-check';
+      }
+
+      issues.push(issue);
+      continue;
+    }
+
+    // Validate anchor if present
+    if (anchor) {
+      const targetContent = fs.readFileSync(targetFile, 'utf-8');
+      const anchors = extractAnchors(targetContent);
+
+      if (!anchors.has(anchor)) {
+        issues.push({
+          type: 'broken-anchor',
+          linkText,
+          href,
+          anchor,
+          status: 'manual-check',
+          message: `Anchor "#${anchor}" not found`,
+        });
+      }
+    }
+  }
+
+  return { content, issues };
+}
+
+/**
+ * Apply fixes to file content
+ */
+function applyFixes(content, issues) {
+  let updated = content;
+
+  for (const issue of issues) {
+    if (issue.status === 'auto-fixable' && issue.suggestedFix) {
+      const oldLink = `[${issue.linkText}](${issue.href})`;
+      const newLink = `[${issue.linkText}](${issue.suggestedFix})`;
+      updated = updated.replace(oldLink, newLink);
+    }
+  }
+
+  return updated;
+}
+
+// Main execution
+console.log(`\nValidating docs in: ${DOCS_ROOT}`);
+console.log(`Mode: ${DRY_RUN ? 'DRY RUN (use --write to fix)' : 'WRITE MODE'}\n`);
+
+const files = getMarkdownFiles(DOCS_ROOT);
+console.log(`Found ${files.length} markdown files\n`);
+
+let totalIssues = 0;
+let autoFixable = 0;
+let needsReview = 0;
+let manualCheck = 0;
+let filesWithIssues = 0;
+
+const allIssues = [];
+
+for (const filePath of files) {
+  const relativePath = path.relative(DOCS_ROOT, filePath);
+  const { content, issues } = processFile(filePath);
+
+  if (issues.length > 0) {
+    filesWithIssues++;
+    totalIssues += issues.length;
+
+    console.log(`\n${relativePath}`);
+
+    for (const issue of issues) {
+      if (issue.status === 'auto-fixable') {
+        autoFixable++;
+        console.log(`  [FIX] ${issue.href}`);
+        console.log(`     -> ${issue.suggestedFix}`);
+      } else if (issue.status === 'needs-review') {
+        needsReview++;
+        console.log(`  [REVIEW] ${issue.href}`);
+        console.log(`     Multiple matches found:`);
+        for (const candidate of issue.candidates) {
+          console.log(`       - ${candidate}`);
+        }
+      } else if (issue.type === 'broken-anchor') {
+        manualCheck++;
+        console.log(`  [MANUAL] ${issue.href}`);
+        console.log(`     ${issue.message}`);
+      } else {
+        manualCheck++;
+        console.log(`  [MANUAL] ${issue.href}`);
+        console.log(`     File not found anywhere - may need to remove link`);
+      }
+
+      allIssues.push({ file: relativePath, ...issue });
+    }
+
+    // Apply fixes if not dry run
+    if (!DRY_RUN) {
+      const fixableIssues = issues.filter((i) => i.status === 'auto-fixable');
+      if (fixableIssues.length > 0) {
+        const updated = applyFixes(content, fixableIssues);
+        fs.writeFileSync(filePath, updated, 'utf-8');
+      }
+    }
+  }
+}
+
+console.log(`\n${'─'.repeat(60)}`);
+console.log(`\nSummary:`);
+console.log(`   Files scanned: ${files.length}`);
+console.log(`   Files with issues: ${filesWithIssues}`);
+console.log(`   Total issues: ${totalIssues}`);
+
+if (totalIssues > 0) {
+  console.log(`\n   Breakdown:`);
+  console.log(`     Auto-fixable:  ${autoFixable}`);
+  console.log(`     Needs review:  ${needsReview}`);
+  console.log(`     Manual check:  ${manualCheck}`);
+}
+
+if (totalIssues === 0) {
+  console.log(`\n   All links valid!`);
+} else if (DRY_RUN && autoFixable > 0) {
+  console.log(`\nRun with --write to auto-fix ${autoFixable} issue(s)`);
+}
+
+console.log('');
+
+process.exit(totalIssues > 0 ? 1 : 0);

package/lib/bmad-cache/bmb/tools/validate-file-refs.mjs

@@ -223,7 +223,7 @@ function isExternalRef(refStr, moduleCode) {
   const match = refStr.match(/\{project-root\}\/_bmad\/([^/]+)\//);
   if (!match) return false;
   const refModule = match[1];
-  // _memory, _config are special framework paths, not external modules
+  // .memory, _config are special framework paths, not external modules
   if (refModule.startsWith('_')) return false;
   return refModule !== moduleCode;
 }

package/lib/bmad-cache/cache-manifest.json

@@ -1,30 +1,36 @@
 {
-  "generated": "2026-03-17T12:12:36.622Z",
-  "bmadMethodVersion": "6.0.4",
+  "generated": "2026-03-28T12:59:06.172Z",
+  "bmadMethodVersion": "6.2.1",
   "modules": {
     "bmb": {
       "url": "https://github.com/bmad-code-org/bmad-builder",
       "branch": "main",
-      "commitSha": "4a790580a7812415bf7122c0e5680679af0527a9",
-      "clonedAt": "2026-03-17T12:11:16.328Z"
+      "commitSha": "9a4ae856c2370fbee3d7e6e1b856725d809f7b53",
+      "clonedAt": "2026-03-28T12:58:52.327Z"
     },
     "cis": {
       "url": "https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite",
       "branch": "main",
-      "commitSha": "e6f643917d5493f097fd04b2b79644b16d7890dc",
-      "clonedAt": "2026-03-17T12:11:26.877Z"
+      "commitSha": "1384f150290b63ec3d03b3a09413e5111ee0aebb",
+      "clonedAt": "2026-03-28T12:58:54.202Z"
     },
     "gds": {
       "url": "https://github.com/bmad-code-org/bmad-module-game-dev-studio.git",
       "branch": "main",
-      "commitSha": "de35f329fd0583066c3f18909162fa55301cba47",
-      "clonedAt": "2026-03-17T12:11:42.947Z"
+      "commitSha": "4744dea5fbfd5d23f3604aa9e83904b99473f6b7",
+      "clonedAt": "2026-03-28T12:58:56.135Z"
     },
     "tea": {
       "url": "https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise",
       "branch": "main",
-      "commitSha": "494044af3cb1723c2f32ca06cc5f5adaddfa24a7",
-      "clonedAt": "2026-03-17T12:12:36.622Z"
+      "commitSha": "bd2ac72a4def9e8b0881407827293d66d9b009d5",
+      "clonedAt": "2026-03-28T12:59:03.930Z"
+    },
+    "wds": {
+      "url": "https://github.com/bmad-code-org/bmad-method-wds-expansion",
+      "branch": "main",
+      "commitSha": "ecb05128973f2a8c6f7da4eead6c682fb1b413bc",
+      "clonedAt": "2026-03-28T12:59:06.172Z"
     }
   }
 }