bmad-code-org/BMAD-METHOD · error · Error

Obsolete implementation terminology found in deployable docu

Error message

Obsolete implementation terminology found in deployable documentation:
  ${details}

What it means

Thrown by validatePublishedImplementationModel when published site files contain forbidden legacy implementation terms (e.g. bmad-quick-dev, create-story, dev-story, quick-flow, plus French/Czech/Vietnamese/Chinese translations). The validator enforces that deployed docs use only the canonical 'Build' workflow vocabulary, scanning .html/.txt/.xml/.json/.svg files under siteDir.

Source

Thrown at tools/validate-published-implementation-model.mjs:26

  /\bbmad-(?:quick-dev|dev-auto)\b/gi,
  /\bQuick[ -]?Dev\b/gi,
  /\bDev[ -]?Auto\b/gi,
  /\bbmad-(?:create|dev)-story\b/gi,
  /\b(?:create-story|dev-story)\b/gi,
  /\b(?:Create Story|Dev Story)\b/g,
  /\b(?:createStory|devStory|create_story|dev_story)\b/g,
  /\bquick[ -]?flow\b/gi,
  /flux rapide|parcours parallèle/gi,
  /paralelní cesta/gi,
  /luồng nhanh|nhánh nhanh/gi,
  /快速流程|并行快线/g,
];

export function validatePublishedImplementationModel(siteDir) {
  const findings = findObsoleteImplementationTerms(siteDir);
  if (findings.length > 0) {
    const details = findings.map(({ file, line, match }) => `${file}:${line}: ${match}`).join('\n  ');
    throw new Error(`Obsolete implementation terminology found in deployable documentation:\n  ${details}`);
  }

  const llmsPath = path.join(siteDir, 'llms.txt');
  const llmsContent = fs.readFileSync(llmsPath, 'utf-8');
  if (!llmsContent.includes(CANONICAL_LLMS_ENTRY) || !llmsContent.includes(CANONICAL_LLMS_DESCRIPTION)) {
    throw new Error('llms.txt must describe Build as canonical for both direct intent and fully planned work');
  }
}

export function findObsoleteImplementationTerms(siteDir) {
  const findings = [];

  for (const filePath of getPublishedTextFiles(siteDir)) {
    const content = fs.readFileSync(filePath, 'utf-8');
    for (const pattern of FORBIDDEN_TERMS) {
      for (const match of content.matchAll(pattern)) {
        findings.push({
          file: path.relative(siteDir, filePath),

View on GitHub (pinned to b70486b9bd)

Solutions

Grep the published site for the terms listed in the error and replace them with the canonical 'Build' vocabulary.
Re-run the site build so stale HTML is regenerated from corrected source markdown.
Add a source-side terminology lint so deprecated words are caught pre-build, not just post-build.

Example fix

<!-- before: docs/reference.md -->
<!--   Use the bmad-quick-dev workflow for fast iteration. -->
<!--
-- after -->
<!--   Use the Build workflow for fast iteration. -->

Defensive patterns

Strategy: validation

Validate before calling

const findings = findObsoleteImplementationTerms(siteDir);
if (findings.length > 0) {
  console.error('Obsolete terms found pre-publish:', findings);
  process.exit(1);
}
validatePublishedImplementationModel(siteDir);

Try / catch

try {
  validatePublishedImplementationModel(siteDir);
} catch (e) {
  if (/Obsolete implementation terminology/.test(e.message)) {
    // parse file:line:match lines, fix each source doc, rebuild, re-run
  } else { throw e; }
}

Prevention

Run findObsoleteImplementationTerms as a pre-commit lint on source docs, not just post-build.
Maintain the canonical-vocabulary list alongside the rename so docs and validator stay in sync.
Rebuild the site fully before validating so stale HTML doesn't trigger false positives.

When it happens

Trigger: Running the validator (typically in CI or a post-build script) against the built siteDir; any published output file matches one of the FORBIDDEN_TERMS regexes.

Common situations: A workflow rename left stale references in docs that flowed into the build; a doc PR reintroduces old terminology; generated/cached HTML wasn't rebuilt after source fixes; translation files still carry deprecated terms.

Related errors

AI-assisted analysis of bmad-code-org/BMAD-METHOD@b70486b9bd (2026-08-13). Data as JSON: /api/errors/20eaf94c15b8551d. Report an issue: GitHub.