bmad-method 6.7.1-next.5 → 6.7.1-next.7

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.7.1-next.5",
+  "version": "6.7.1-next.7",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -31,6 +31,7 @@
     "docs:fix-links": "node tools/fix-doc-links.js",
     "docs:preview": "astro preview --root website",
     "docs:validate-links": "node tools/validate-doc-links.js",
+    "docs:validate-sidebar": "node tools/validate-sidebar-order.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
@@ -39,7 +40,7 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
     "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",

package/removals.txt

@@ -57,3 +57,6 @@ bmad-bmm-validate-prd
 # bmad-distillator: superseded by bmad-spec (universal intent distiller with
 # preservation-validated contract for downstream skills).
 bmad-distillator
+# bmad-create-ux-design: renamed to bmad-ux (spine-based skill with separate
+# DESIGN.md and EXPERIENCE.md outputs).
+bmad-create-ux-design

package/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Mary, let's brainstorm"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Paige, let's document this codebase"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/1-analysis/bmad-document-project/SKILL.md

@@ -55,7 +55,7 @@ Greet `{user_name}` (if you have not already), speaking in `{communication_langu
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Execution
 

package/src/bmm-skills/1-analysis/bmad-prfaq/SKILL.md

@@ -65,7 +65,7 @@ Greet `{user_name}`, speaking in `{communication_language}`. Be warm but efficie
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Continue below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Pre-workflow Setup
 

package/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md

@@ -21,7 +21,10 @@ At the opening greeting, let the user know they can invoke `bmad-party-mode` for
 4. `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers in `## Discovery`, org tools preferred when their directive matches. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant.
 5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
 6. Greet `{user_name}` in `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`.
-7. Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Intent Operating Modes
 

package/src/bmm-skills/1-analysis/research/bmad-domain-research/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## QUICK TOPIC DISCOVERY
 

package/src/bmm-skills/1-analysis/research/bmad-market-research/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## QUICK TOPIC DISCOVERY
 

package/src/bmm-skills/1-analysis/research/bmad-technical-research/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## QUICK TOPIC DISCOVERY
 

package/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey John, let's write the PRD"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Sally, let's design the UX"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md

@@ -20,7 +20,10 @@ You are a master facilitator and coach helping the user create, edit, or validat
 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-quick-dev`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.
 5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, scan `{workflow.prd_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `prd.md` frontmatter `status` is not `final`); if any exist, offer to resume rather than starting over.
-6. Run `{workflow.activation_steps_append}`.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Intent Modes
 

package/src/bmm-skills/2-plan-workflows/bmad-ux/SKILL.md

@@ -35,7 +35,10 @@ UX may lead, follow, or stand alone. Inherit `sources:` by reference; the spines
 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn. In the greeting, let the user know `bmad-party-mode` and `bmad-advanced-elicitation` are always available. Then scan for misroute on the first message: PRD → `bmad-prd`; architecture → `bmad-create-architecture`; game UX → BMad GDS; agent/skill → `bmad-workflow-builder`; brief → `bmad-product-brief`.
 5. Detect intent: **Create**, **Update**, **Validate**. For Create, before binding a fresh workspace, scan `{workflow.ux_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `DESIGN.md` frontmatter `status` is not `final`) and offer to resume rather than starting over.
-6. Run `{workflow.activation_steps_append}`.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Modes
 

package/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Winston, let's architect this"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/3-solutioning/bmad-check-implementation-readiness/SKILL.md

@@ -84,7 +84,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Execution
 

package/src/bmm-skills/3-solutioning/bmad-create-architecture/SKILL.md

@@ -65,7 +65,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Execution
 

package/src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/SKILL.md

@@ -86,7 +86,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Execution
 

package/src/bmm-skills/3-solutioning/bmad-generate-project-context/SKILL.md

@@ -65,7 +65,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md

@@ -63,6 +63,8 @@ Continue to prefix your messages with `{agent.icon}` throughout the session so t
 
 Execute each entry in `{agent.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 8: Dispatch or Present the Menu
 
 If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Amelia, let's implement the next story"), skip the menu and dispatch that item directly after greeting.

package/src/bmm-skills/4-implementation/bmad-checkpoint-preview/SKILL.md

@@ -55,7 +55,7 @@ Greet the user, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Global Step Rules (apply to every step)
 

package/src/bmm-skills/4-implementation/bmad-code-review/SKILL.md

@@ -58,7 +58,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## WORKFLOW ARCHITECTURE
 

package/src/bmm-skills/4-implementation/bmad-correct-course/SKILL.md

@@ -62,7 +62,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md

@@ -63,7 +63,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-dev-story/SKILL.md

@@ -64,7 +64,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-investigate/SKILL.md

@@ -79,6 +79,8 @@ Greet `{user_name}` in `{communication_language}`.
 
 Run each entry in `{workflow.activation_steps_append}` in order.
 
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
 ### Step 7: Acknowledge and route
 
 Acknowledge the input as a reference (record paths and IDs; don't read raw content). Path to an existing case file →

package/src/bmm-skills/4-implementation/bmad-qa-generate-e2e-tests/SKILL.md

@@ -56,7 +56,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/SKILL.md

@@ -79,7 +79,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## WORKFLOW ARCHITECTURE
 

package/src/bmm-skills/4-implementation/bmad-retrospective/SKILL.md

@@ -73,7 +73,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-sprint-planning/SKILL.md

@@ -59,7 +59,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/bmm-skills/4-implementation/bmad-sprint-status/SKILL.md

@@ -57,7 +57,7 @@ Greet `{user_name}`, speaking in `{communication_language}`.
 
 Execute each entry in `{workflow.activation_steps_append}` in order.
 
-Activation is complete. Begin the workflow below.
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Paths
 

package/src/core-skills/bmad-spec/SKILL.md

@@ -22,7 +22,10 @@ Multiple skills may call to update the same spec over time.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded).
 3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field.
-5. Run `{workflow.activation_steps_append}`.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
 
 ## Workspace
 

package/tools/validate-sidebar-order.js

@@ -0,0 +1,388 @@
+/**
+ * Sidebar Order Validator
+ *
+ * Validates sidebar.order values in YAML frontmatter of markdown doc files.
+ *
+ * English docs — strict (errors):
+ *   - Duplicate sidebar.order values within the same directory
+ *   - Gaps in the ordering sequence
+ *   - sidebar: block present but missing or invalid order: field
+ *
+ * Translations — errors + warnings:
+ *   - Same structural rules as English (duplicates, gaps) — errors
+ *   - Order drift from English counterpart — warnings (non-blocking)
+ *
+ * Usage:
+ *   node tools/validate-sidebar-order.js
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DOCS_ROOT = path.resolve(__dirname, '../docs');
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+const LOCALE_RE = /^[a-z]{2}(?:-[a-zA-Z0-9]+)*$/;
+const MAX_GAPS = 50;
+
+// ── Main ─────────────────────────────────────────────────────────────────
+
+/**
+ * Scan all docs, validate sidebar orders, and report errors/warnings.
+ * Exits 0 on success, 1 if any errors found.
+ */
+function main() {
+  if (!fs.existsSync(DOCS_ROOT)) {
+    console.error(`Error: docs directory not found at ${DOCS_ROOT}`);
+    process.exit(1);
+  }
+
+  const { languageDirs, englishSections } = classifyDocsDirs();
+  console.log(`\nValidating sidebar ordering in: ${DOCS_ROOT}\n`);
+  console.log(`English sections: ${englishSections.join(', ')}`);
+  console.log(`Translation languages: ${languageDirs.join(', ')}\n`);
+
+  const allErrors = [];
+  const allWarnings = [];
+  const englishOrderMaps = new Map();
+
+  for (const section of englishSections) {
+    const sectionDir = path.join(DOCS_ROOT, section);
+    if (!fs.existsSync(sectionDir)) continue;
+
+    console.log(`\nChecking English docs/${section}/`);
+    const { orderMap, issues } = checkDirectory(sectionDir);
+    englishOrderMaps.set(section, orderMap);
+
+    for (const issue of issues) {
+      allErrors.push(issue);
+      reportIssue(issue, '  ', `docs/${section}`);
+    }
+    if (issues.length === 0) {
+      console.log(`  [OK] docs/${section}/ — all orders valid`);
+    }
+  }
+
+  for (const lang of languageDirs) {
+    const langDir = path.join(DOCS_ROOT, lang);
+    const langSections = fs
+      .readdirSync(langDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && !e.name.startsWith('_'))
+      .map((e) => e.name);
+
+    console.log(`\nChecking ${lang}/ docs`);
+
+    for (const section of langSections) {
+      const sectionDir = path.join(langDir, section);
+      if (!fs.existsSync(sectionDir)) continue;
+
+      console.log(`  ${lang}/${section}/`);
+      const { issues } = checkDirectory(sectionDir);
+
+      for (const issue of issues) {
+        allErrors.push(issue);
+        reportIssue(issue, '    ', `${lang}/${section}`);
+      }
+      if (issues.length === 0) {
+        console.log(`    [OK] ${lang}/${section}/ — all orders valid`);
+      }
+    }
+
+    for (const w of checkTranslationDrift(lang, langSections, englishOrderMaps)) {
+      allWarnings.push(w);
+      const langDisplay = w.langOrder === null ? 'no order' : `order ${w.langOrder}`;
+      console.log(`  [WARN] ${rel(w.file)}: ${langDisplay} (English: ${w.englishOrder})`);
+    }
+  }
+
+  printSummary(allErrors, allWarnings);
+  process.exit(allErrors.length > 0 ? 1 : 0);
+}
+
+// ── Directory classification ─────────────────────────────────────────────
+
+/**
+ * Classify top-level docs/ subdirectories as language dirs or English sections.
+ * Language dirs match BCP 47 locale pattern; everything else is English.
+ * @returns {{ languageDirs: string[], englishSections: string[] }}
+ */
+function classifyDocsDirs() {
+  const dirs = fs.readdirSync(DOCS_ROOT, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('_'));
+
+  const languageDirs = [];
+  const englishSections = [];
+
+  for (const d of dirs) {
+    (LOCALE_RE.test(d.name) ? languageDirs : englishSections).push(d.name);
+  }
+
+  return { languageDirs, englishSections };
+}
+
+// ── Per-directory validation ─────────────────────────────────────────────
+
+/**
+ * Validate sidebar.order values for all markdown files in a directory.
+ * Detects duplicates, gaps in sequence, missing-order, and invalid-order fields.
+ * @param {string} dirPath - Absolute path to the directory to scan.
+ * @returns {{ orderMap: Map<number, string[]>, issues: object[] }}
+ */
+function checkDirectory(dirPath) {
+  const issues = [];
+  const orderMap = new Map();
+  const missingOrder = [];
+  const invalidOrder = [];
+
+  for (const entry of listMdEntries(dirPath)) {
+    const fullPath = path.join(dirPath, entry.name);
+    const result = extractSidebarOrder(fs.readFileSync(fullPath, 'utf-8'));
+
+    if (!result.hasSidebar) continue;
+    if (result.order === null) {
+      if (result.orderInvalid) {
+        invalidOrder.push(fullPath);
+      } else {
+        missingOrder.push(fullPath);
+      }
+      continue;
+    }
+
+    if (!orderMap.has(result.order)) orderMap.set(result.order, []);
+    orderMap.get(result.order).push(fullPath);
+  }
+
+  for (const file of missingOrder) {
+    issues.push({ level: 'error', type: 'missing-order', file, message: 'Has sidebar: block but no order: field' });
+  }
+
+  for (const file of invalidOrder) {
+    issues.push({ level: 'error', type: 'invalid-order', file, message: 'Invalid sidebar.order: must be a positive integer' });
+  }
+
+  for (const [order, files] of orderMap) {
+    if (files.length > 1) {
+      for (const file of files) {
+        issues.push({ level: 'error', type: 'duplicate-order', file, order, message: `Duplicate sidebar.order: ${order}` });
+      }
+    }
+  }
+
+  if (orderMap.size > 0) {
+    let max = -Infinity;
+    for (const k of orderMap.keys()) if (k > max) max = k;
+
+    let gapCount = 0;
+    for (let i = 1; i <= max; i++) {
+      if (!orderMap.has(i)) {
+        issues.push({
+          level: 'error',
+          type: 'gap',
+          directory: dirPath,
+          missing: i,
+          message: `Gap in sidebar order: missing position ${i}`,
+        });
+        gapCount++;
+        if (gapCount >= MAX_GAPS) {
+          issues.push({
+            level: 'error',
+            type: 'gap-truncated',
+            directory: dirPath,
+            message: `Too many gaps (stopped after ${MAX_GAPS}) — check for typos in sidebar.order values`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  return { orderMap, issues };
+}
+
+// ── Cross-language drift ─────────────────────────────────────────────────
+
+/**
+ * Compare translated sidebar orders against English counterparts and warn on drift.
+ * Warns on numeric drift and on translation having sidebar but missing order.
+ * Files without an English counterpart are skipped silently.
+ * @param {string} lang - Language directory name (e.g. "cs", "zh-cn").
+ * @param {string[]} langSections - Section subdirectories within the language folder.
+ * @param {Map<string, Map<number, string[]>>} englishOrderMaps - English order maps keyed by section name.
+ * @returns {object[]} Drift warnings.
+ */
+function checkTranslationDrift(lang, langSections, englishOrderMaps) {
+  const warnings = [];
+
+  for (const section of langSections) {
+    const sectionDir = path.join(DOCS_ROOT, lang, section);
+    if (!fs.existsSync(sectionDir)) continue;
+
+    const englishMap = englishOrderMaps.get(section);
+    if (!englishMap) continue;
+
+    for (const entry of listMdEntries(sectionDir)) {
+      const langFile = path.join(sectionDir, entry.name);
+      const englishFile = path.join(DOCS_ROOT, section, entry.name);
+      if (!fs.existsSync(englishFile)) continue;
+
+      const langResult = extractSidebarOrder(fs.readFileSync(langFile, 'utf-8'));
+      const engResult = extractSidebarOrder(fs.readFileSync(englishFile, 'utf-8'));
+
+      const langHasOrder = typeof langResult.order === 'number';
+      const engHasOrder = typeof engResult.order === 'number';
+
+      if (langHasOrder && engHasOrder && langResult.order !== engResult.order) {
+        warnings.push({
+          level: 'warning',
+          type: 'order-drift',
+          file: langFile,
+          englishFile,
+          langOrder: langResult.order,
+          englishOrder: engResult.order,
+        });
+      } else if (engHasOrder && langResult.hasSidebar && !langHasOrder) {
+        warnings.push({
+          level: 'warning',
+          type: 'order-drift',
+          file: langFile,
+          englishFile,
+          langOrder: null,
+          englishOrder: engResult.order,
+        });
+      }
+    }
+  }
+
+  return warnings;
+}
+
+// ── Output ───────────────────────────────────────────────────────────────
+
+/**
+ * Print a single validation issue to stdout.
+ * @param {object} issue - Issue object with type, file/order/message fields.
+ * @param {string} indent - Whitespace prefix for indentation.
+ * @param {string} ctxPath - Display path for gap issues (e.g. "docs/explanation").
+ */
+function reportIssue(issue, indent, ctxPath) {
+  switch (issue.type) {
+    case 'duplicate-order': {
+      console.log(`${indent}[ERROR] Duplicate order ${issue.order}: ${rel(issue.file)}`);
+      break;
+    }
+    case 'gap': {
+      console.log(`${indent}[ERROR] ${issue.message} in ${ctxPath}/`);
+      break;
+    }
+    case 'gap-truncated': {
+      console.log(`${indent}[ERROR] ${issue.message}`);
+      break;
+    }
+    case 'missing-order': {
+      console.log(`${indent}[ERROR] ${issue.message}: ${rel(issue.file)}`);
+      break;
+    }
+    case 'invalid-order': {
+      console.log(`${indent}[ERROR] ${issue.message}: ${rel(issue.file)}`);
+      break;
+    }
+  }
+}
+
+/**
+ * Print summary with error/warning counts and error type breakdown.
+ * @param {object[]} errors - All collected errors.
+ * @param {object[]} warnings - All collected warnings.
+ */
+function printSummary(errors, warnings) {
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log('\nSummary:');
+  console.log(`   Errors:   ${errors.length}`);
+  console.log(`   Warnings: ${warnings.length}`);
+
+  if (errors.length > 0) {
+    const breakdown = {};
+    for (const e of errors) breakdown[e.type] = (breakdown[e.type] || 0) + 1;
+    console.log('\n   Error breakdown:');
+    for (const [type, count] of Object.entries(breakdown)) console.log(`     ${type}: ${count}`);
+  }
+
+  if (errors.length === 0 && warnings.length === 0) {
+    console.log('\n   All sidebar orders valid!');
+  }
+
+  console.log('');
+}
+
+// ── Leaf helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Convert an absolute path to one relative to DOCS_ROOT.
+ * @param {string} filePath - Absolute file path.
+ * @returns {string} Relative path from docs root.
+ */
+function rel(filePath) {
+  return path.relative(DOCS_ROOT, filePath);
+}
+
+/**
+ * Extract sidebar.order from YAML frontmatter.
+ * Handles block mapping (sidebar:\n  order: 5) and flow mapping (sidebar: { order: 5 }).
+ * Only matches order: as a direct child of sidebar:, not from nested blocks.
+ * @param {string} content - Full file contents of a markdown file.
+ * @returns {{ hasSidebar: boolean, order?: number|null, orderInvalid?: boolean }}
+ */
+function extractSidebarOrder(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { hasSidebar: false };
+
+  const frontmatter = match[1];
+
+  // Flow mapping: sidebar: { order: 5 }
+  const inline = frontmatter.match(/^sidebar:[ \t]*\{[^}]*\border:[ \t]*(\d+)/m);
+  if (inline) return validateOrder(inline[1]);
+
+  // Block mapping: sidebar:\n  order: 5
+  if (!/^sidebar:[ \t]*$/m.test(frontmatter)) return { hasSidebar: false };
+
+  const lines = frontmatter.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^sidebar:[ \t]*$/.test(l));
+  let baseIndent = null;
+
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\s*$/.test(line)) continue;
+
+    const indent = line.search(/\S/);
+    if (indent === 0) break;
+    if (baseIndent === null) baseIndent = indent;
+    if (indent < baseIndent) break;
+    if (indent > baseIndent) continue;
+
+    const m = line.match(/^\s+order:[ \t]*(\d+)/);
+    if (m) return validateOrder(m[1]);
+  }
+
+  return { hasSidebar: true, order: null };
+}
+
+/**
+ * Validate a parsed order value and return a result object.
+ * Rejects non-finite values (Infinity, NaN) and non-positive values (0, negative).
+ * @param {string} raw - Raw digit string from frontmatter.
+ * @returns {{ hasSidebar: boolean, order?: number|null, orderInvalid?: boolean }}
+ */
+function validateOrder(raw) {
+  const n = parseInt(raw, 10);
+  if (!Number.isFinite(n) || n < 1) return { hasSidebar: true, order: null, orderInvalid: true };
+  return { hasSidebar: true, order: n };
+}
+
+/**
+ * List markdown files (.md/.mdx) in a directory, excluding subdirectories.
+ * @param {string} dirPath - Absolute path to the directory.
+ * @returns {fs.Dirent[]} Dirent entries for markdown files.
+ */
+function listMdEntries(dirPath) {
+  return fs.readdirSync(dirPath, { withFileTypes: true }).filter((e) => e.isFile() && (e.name.endsWith('.md') || e.name.endsWith('.mdx')));
+}
+
+main();