@mycodemap/mycodemap 0.2.0 → 0.3.4

package/scripts/release.sh

@@ -0,0 +1,142 @@
+#!/bin/bash
+# [META] since:2026-03 | owner:release-team | stable:true
+# [WHY] 发布助手脚本 - 简化版本发布流程
+
+set -e
+
+# 颜色定义
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# 帮助信息
+show_help() {
+    echo "用法: ./scripts/release.sh [选项]"
+    echo ""
+    echo "选项:"
+    echo "  patch    发布 patch 版本 (0.2.0 -> 0.2.1)"
+    echo "  minor    发布 minor 版本 (0.2.0 -> 0.3.0)"
+    echo "  major    发布 major 版本 (0.2.0 -> 1.0.0)"
+    echo "  <版本>   指定具体版本号 (例如: 0.2.1)"
+    echo "  --help   显示此帮助信息"
+    echo ""
+    echo "示例:"
+    echo "  ./scripts/release.sh patch    # 发布 patch 版本"
+    echo "  ./scripts/release.sh 0.3.0    # 发布指定版本"
+}
+
+# 检查参数
+if [ $# -eq 0 ] || [ "$1" == "--help" ]; then
+    show_help
+    exit 0
+fi
+
+VERSION_TYPE=$1
+
+# 检查是否在 git 仓库中
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo -e "${RED}❌ 错误: 当前目录不是 git 仓库${NC}"
+    exit 1
+fi
+
+# 检查工作区是否干净
+if [ -n "$(git status --porcelain)" ]; then
+    echo -e "${YELLOW}⚠️  警告: 工作区有未提交的修改${NC}"
+    git status --short
+    echo ""
+    read -p "是否继续? (y/N): " confirm
+    if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
+        echo -e "${RED}❌ 发布已取消${NC}"
+        exit 1
+    fi
+    echo ""
+fi
+
+# 获取当前版本
+CURRENT_VERSION=$(node -p "require('./package.json').version")
+echo -e "${BLUE}📦 当前版本: $CURRENT_VERSION${NC}"
+
+# 计算新版本
+case $VERSION_TYPE in
+    patch)
+        NEW_VERSION=$(npm version patch --no-git-tag-version)
+        NEW_VERSION=${NEW_VERSION#v}
+        ;;
+    minor)
+        NEW_VERSION=$(npm version minor --no-git-tag-version)
+        NEW_VERSION=${NEW_VERSION#v}
+        ;;
+    major)
+        NEW_VERSION=$(npm version major --no-git-tag-version)
+        NEW_VERSION=${NEW_VERSION#v}
+        ;;
+    *)
+        # 验证版本号格式
+        if ! echo "$VERSION_TYPE" | grep -E '^[0-9]+\.[0-9]+\.[0-9]+' > /dev/null; then
+            echo -e "${RED}❌ 错误: 无效的版本号格式: $VERSION_TYPE${NC}"
+            echo "版本号必须符合 semver 格式，例如: 0.2.1, 1.0.0"
+            exit 1
+        fi
+        NEW_VERSION=$VERSION_TYPE
+        npm version $NEW_VERSION --no-git-tag-version --allow-same-version 2>/dev/null || true
+        ;;
+esac
+
+echo -e "${GREEN}🚀 新版本: $NEW_VERSION${NC}"
+echo ""
+
+# 确认发布
+read -p "确认发布 v$NEW_VERSION? (y/N): " confirm
+if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
+    # 恢复 package.json
+    git checkout package.json package-lock.json 2>/dev/null || true
+    echo -e "${RED}❌ 发布已取消${NC}"
+    exit 1
+fi
+
+echo ""
+echo -e "${BLUE}📋 发布步骤:${NC}"
+echo ""
+
+# 步骤 1: 运行检查
+echo -e "${BLUE}1/5 运行代码检查...${NC}"
+npm run check:all
+echo -e "${GREEN}   ✅ 检查通过${NC}"
+echo ""
+
+# 步骤 2: 提交版本更新
+echo -e "${BLUE}2/5 提交版本更新...${NC}"
+git add package.json package-lock.json
+git commit -m "[RELEASE] bump version to v$NEW_VERSION"
+echo -e "${GREEN}   ✅ 已提交版本更新${NC}"
+echo ""
+
+# 步骤 3: 创建标签
+echo -e "${BLUE}3/5 创建 git tag...${NC}"
+git tag -a "v$NEW_VERSION" -m "Release v$NEW_VERSION"
+echo -e "${GREEN}   ✅ 已创建标签: v$NEW_VERSION${NC}"
+echo ""
+
+# 步骤 4: 推送
+echo -e "${BLUE}4/5 推送到远程仓库...${NC}"
+git push origin HEAD
+git push origin "v$NEW_VERSION"
+echo -e "${GREEN}   ✅ 已推送到远程${NC}"
+echo ""
+
+# 步骤 5: 完成
+echo -e "${GREEN}5/5 🎉 发布流程已触发!${NC}"
+echo ""
+echo -e "${BLUE}GitHub Actions 将会自动:${NC}"
+echo "  • 构建项目"
+echo "  • 运行测试"
+echo "  • 发布到 NPM"
+echo "  • 创建 GitHub Release"
+echo ""
+echo -e "${BLUE}查看发布状态:${NC}"
+echo "  https://github.com/$(git remote get-url origin | sed 's/.*github.com[:/]//;s/.git$//')/actions"
+echo ""
+echo -e "${BLUE}NPM 包页面:${NC}"
+echo "  https://www.npmjs.com/package/@mycodemap/mycodemap"

package/scripts/run-benchmark.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# [META] CodeMap 基准测试运行脚本
+# [WHY] 基准测试运行时间长，需要单独执行而非包含在常规测试中
+
+set -e
+
+echo "==================================="
+echo "CodeMap 基准测试"
+echo "==================================="
+echo ""
+echo "注意：此测试运行 30 个查询，每个查询最多 5 秒"
+echo "预计总时间：30 秒 - 2 分钟"
+echo ""
+
+# 确保已构建
+echo "[1/2] 检查构建状态..."
+if [ ! -d "dist" ]; then
+    echo "  需要构建项目..."
+    npm run build
+fi
+
+# 运行基准测试
+echo "[2/2] 运行基准测试..."
+npx vitest run --config vitest.benchmark.config.ts "$@"
+
+echo ""
+echo "==================================="
+echo "基准测试完成"
+echo "==================================="

package/scripts/validate-ai-docs.js

@@ -0,0 +1,294 @@
+// [META] since:2026-03-22 | owner:docs-team | stable:true
+// [WHY] 验证 AI 友好文档的完整性和合规性
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '..');
+
+// AI 文档清单
+const requiredAIDocs = [
+  { file: 'llms.txt', minLength: 50 },  // 标准 llms.txt 格式
+  { file: 'AI_GUIDE.md', minLength: 100 },
+  { file: 'AI_DISCOVERY.md', minLength: 100 },
+  { file: 'ai-document-index.yaml', minLength: 50 },
+  { file: 'docs/ai-guide/README.md', minLength: 50 },
+  { file: 'docs/ai-guide/QUICKSTART.md', minLength: 50 },
+  { file: 'docs/ai-guide/COMMANDS.md', minLength: 100 },
+  { file: 'docs/ai-guide/OUTPUT.md', minLength: 100 },
+  { file: 'docs/ai-guide/PATTERNS.md', minLength: 100 },
+  { file: 'docs/ai-guide/PROMPTS.md', minLength: 100 },
+  { file: 'docs/ai-guide/INTEGRATION.md', minLength: 100 },
+];
+
+// IDE 特定的可选文档
+const optionalIDEFiles = [
+  { file: '.cursorrules', description: 'Cursor IDE rules' },
+  { file: '.github/copilot-instructions.md', description: 'GitHub Copilot instructions' },
+];
+
+// AI 友好性检查清单
+// 注意：不是所有文档都需要所有检查项
+const aiFriendlyChecks = [
+  { pattern: /^##+\s+/m, name: '层级标题（##）', requiredFor: 'all' },
+  { pattern: /\|.*\|.*\|/, name: '表格（速查表）', requiredFor: 'all' },
+  { pattern: /```(bash|typescript|json|python)/, name: '可执行代码块', requiredFor: ['AI_GUIDE.md', 'QUICKSTART.md', 'COMMANDS.md', 'PATTERNS.md', 'PROMPTS.md', 'INTEGRATION.md'] },
+  { pattern: /interface\s+\w+|type\s+\w+|function\s+\w+/, name: '代码定义', requiredFor: ['OUTPUT.md', 'PATTERNS.md', 'INTEGRATION.md'] },
+  { pattern: /决策树|流程图|速查表|提示词|模板|模式|示例/, name: 'AI 友好关键词', requiredFor: 'all' },
+];
+
+function readText(filePath) {
+  const absolutePath = path.join(rootDir, filePath);
+  if (!existsSync(absolutePath)) {
+    return null;
+  }
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function checkRequiredDocs(failures) {
+  console.log('Checking required AI documents...\n');
+  
+  for (const { file, minLength } of requiredAIDocs) {
+    const content = readText(file);
+    
+    if (!content) {
+      failures.push(`Missing required AI doc: ${file}`);
+      continue;
+    }
+    
+    const lines = content.split('\n').length;
+    if (lines < minLength) {
+      failures.push(`${file} is too short (${lines} lines, min ${minLength})`);
+    }
+    
+    console.log(`  ✅ ${file} (${lines} lines)`);
+  }
+  
+  // 检查可选 IDE 文件
+  console.log('\nChecking optional IDE-specific files...\n');
+  for (const { file, description } of optionalIDEFiles) {
+    const content = readText(file);
+    if (content) {
+      const lines = content.split('\n').length;
+      console.log(`  ✅ ${file} (${lines} lines) - ${description}`);
+    } else {
+      console.log(`  ⚠️  ${file} - ${description} (optional, not found)`);
+    }
+  }
+}
+
+function checkAIFriendliness(failures) {
+  console.log('\nChecking AI friendliness...\n');
+  
+  const aiDocs = requiredAIDocs.map(d => d.file);
+  
+  for (const doc of aiDocs) {
+    const content = readText(doc);
+    if (!content) continue;
+    
+    const docName = path.basename(doc);
+    const docFailures = [];
+    
+    // llms.txt 文件检查标准格式
+    if (doc === 'llms.txt') {
+      // 检查 llms.txt 标准结构 (支持中英文)
+      const hasH1 = /^#\s+\w+/m.test(content);
+      const hasSummary = /^>\s+/m.test(content);
+      const hasDocsSection = /##\s*(?:文档|Docs|快速开始|Quick Start)/i.test(content);
+      
+      if (!hasH1) docFailures.push('missing H1 title (llms.txt standard)');
+      if (!hasSummary) docFailures.push('missing blockquote summary (llms.txt standard)');
+      if (!hasDocsSection) docFailures.push('missing ## Docs/文档 section (llms.txt standard)');
+      
+      if (docFailures.length > 0) {
+        failures.push(`${doc}: ${docFailures.join(', ')}`);
+        console.log(`  ❌ ${doc}`);
+        docFailures.forEach(f => console.log(`      - ${f}`));
+      } else {
+        console.log(`  ✅ ${doc} (llms.txt standard format)`);
+      }
+      continue;
+    }
+    
+    // YAML 文件有独立的检查标准
+    if (doc.endsWith('.yaml') || doc.endsWith('.yml')) {
+      // 检查 YAML 基本结构
+      if (!content.includes('project:') || !content.includes('documentation:')) {
+        docFailures.push('missing required YAML structure');
+      }
+      if (docFailures.length > 0) {
+        failures.push(`${doc}: ${docFailures.join(', ')}`);
+        console.log(`  ❌ ${doc}`);
+        docFailures.forEach(f => console.log(`      - ${f}`));
+      } else {
+        console.log(`  ✅ ${doc} (YAML format)`);
+      }
+      continue;
+    }
+    
+    for (const { pattern, name, requiredFor } of aiFriendlyChecks) {
+      // 检查此文档是否需要此项
+      const isRequired = requiredFor === 'all' || 
+                        (Array.isArray(requiredFor) && requiredFor.includes(docName));
+      
+      if (!isRequired) continue;
+      
+      if (!pattern.test(content)) {
+        docFailures.push(`missing ${name}`);
+      }
+    }
+    
+    if (docFailures.length > 0) {
+      failures.push(`${doc}: ${docFailures.join(', ')}`);
+      console.log(`  ❌ ${doc}`);
+      docFailures.forEach(f => console.log(`      - ${f}`));
+    } else {
+      console.log(`  ✅ ${doc}`);
+    }
+  }
+}
+
+function checkCrossReferences(failures) {
+  console.log('\nChecking cross-references...\n');
+  
+  // README.md 必须链接到 AI_GUIDE.md
+  const readme = readText('README.md');
+  if (readme) {
+    if (!readme.includes('AI_GUIDE.md')) {
+      failures.push('README.md must reference AI_GUIDE.md');
+      console.log('  ❌ README.md missing AI_GUIDE.md link');
+    } else {
+      console.log('  ✅ README.md links to AI_GUIDE.md');
+    }
+  }
+  
+  // AGENTS.md 必须包含 AI 文档规范
+  const agents = readText('AGENTS.md');
+  if (agents) {
+    if (!agents.includes('AI 友好')) {
+      failures.push('AGENTS.md must contain AI-friendly doc requirements');
+      console.log('  ❌ AGENTS.md missing AI-friendly requirements');
+    } else {
+      console.log('  ✅ AGENTS.md contains AI-friendly requirements');
+    }
+  }
+  
+  // CLAUDE.md 必须链接到 AI 文档
+  const claude = readText('CLAUDE.md');
+  if (claude) {
+    if (!claude.includes('AI_GUIDE.md') || !claude.includes('docs/ai-guide/')) {
+      failures.push('CLAUDE.md must reference AI docs');
+      console.log('  ❌ CLAUDE.md missing AI docs references');
+    } else {
+      console.log('  ✅ CLAUDE.md links to AI docs');
+    }
+  }
+  
+  // AI_GUIDE.md 必须链接到 AI_DISCOVERY.md 和 ai-document-index.yaml
+  const aiGuide = readText('AI_GUIDE.md');
+  if (aiGuide) {
+    if (!aiGuide.includes('AI_DISCOVERY.md')) {
+      failures.push('AI_GUIDE.md must reference AI_DISCOVERY.md');
+      console.log('  ❌ AI_GUIDE.md missing AI_DISCOVERY.md link');
+    } else {
+      console.log('  ✅ AI_GUIDE.md links to AI_DISCOVERY.md');
+    }
+    
+    if (!aiGuide.includes('ai-document-index.yaml')) {
+      failures.push('AI_GUIDE.md must reference ai-document-index.yaml');
+      console.log('  ❌ AI_GUIDE.md missing ai-document-index.yaml link');
+    } else {
+      console.log('  ✅ AI_GUIDE.md links to ai-document-index.yaml');
+    }
+  }
+  
+  // llms.txt 必须链接到主要 AI 文档
+  const llmsTxt = readText('llms.txt');
+  if (llmsTxt) {
+    const requiredLinks = ['AI_GUIDE.md', 'ai-document-index.yaml'];
+    const missingLinks = requiredLinks.filter(link => !llmsTxt.includes(link));
+    
+    if (missingLinks.length > 0) {
+      failures.push(`llms.txt must reference: ${missingLinks.join(', ')}`);
+      console.log(`  ❌ llms.txt missing links: ${missingLinks.join(', ')}`);
+    } else {
+      console.log('  ✅ llms.txt links to AI_GUIDE.md and ai-document-index.yaml');
+    }
+  }
+}
+
+function checkPromptsLibrary(failures) {
+  console.log('\nChecking prompts library...\n');
+  
+  const promptsFile = readText('docs/ai-guide/PROMPTS.md');
+  if (!promptsFile) {
+    failures.push('PROMPTS.md is required for AI prompts library');
+    return;
+  }
+  
+  // 检查是否包含常见的提示词模板
+  const requiredPrompts = [
+    { pattern: /项目理解|理解项目/, name: '项目理解模板' },
+    { pattern: /变更影响|影响分析/, name: '变更影响分析模板' },
+    { pattern: /代码搜索|查找.*代码/, name: '代码搜索模板' },
+    { pattern: /重构|refactor/i, name: '重构评估模板' },
+  ];
+  
+  for (const { pattern, name } of requiredPrompts) {
+    if (!pattern.test(promptsFile)) {
+      failures.push(`PROMPTS.md missing: ${name}`);
+      console.log(`  ❌ Missing: ${name}`);
+    } else {
+      console.log(`  ✅ Has: ${name}`);
+    }
+  }
+}
+
+function checkDecisionTrees(failures) {
+  console.log('\nChecking decision trees...\n');
+  
+  const quickstart = readText('docs/ai-guide/QUICKSTART.md');
+  if (quickstart) {
+    // 检查是否有决策树（流程图或层级结构）
+    const hasDecisionTree = /开始.*\n.*↓\n|决策树|流程图/.test(quickstart);
+    
+    if (!hasDecisionTree) {
+      failures.push('QUICKSTART.md must contain decision tree');
+      console.log('  ❌ QUICKSTART.md missing decision tree');
+    } else {
+      console.log('  ✅ QUICKSTART.md has decision tree');
+    }
+  }
+}
+
+function validateAIDocs() {
+  console.log('========================================');
+  console.log('AI Documentation Guardrails Check');
+  console.log('========================================\n');
+  
+  const failures = [];
+  
+  checkRequiredDocs(failures);
+  checkAIFriendliness(failures);
+  checkCrossReferences(failures);
+  checkPromptsLibrary(failures);
+  checkDecisionTrees(failures);
+  
+  console.log('\n========================================');
+  
+  if (failures.length > 0) {
+    console.error('\n❌ AI documentation guardrails failed:\n');
+    for (const failure of failures) {
+      console.error(`  - ${failure}`);
+    }
+    console.log('\n========================================');
+    process.exit(1);
+  }
+  
+  console.log('\n✅ All AI documentation guardrails passed!\n');
+  console.log('========================================');
+}
+
+validateAIDocs();

package/scripts/validate-docs.js

@@ -0,0 +1,238 @@
+// [META] since:2026-03 | owner:docs-team | stable:true
+// [WHY] Validate high-signal documentation facts against the current repository guardrails
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const defaultRootDir = path.resolve(__dirname, '..');
+
+function parseRootDir(argv) {
+  const rootFlagIndex = argv.indexOf('--root');
+  if (rootFlagIndex === -1) {
+    return defaultRootDir;
+  }
+
+  const rootValue = argv[rootFlagIndex + 1];
+  if (!rootValue) {
+    console.error('ERROR: --root requires a directory path');
+    process.exit(1);
+  }
+
+  return path.resolve(rootValue);
+}
+
+function readText(rootDir, relativePath, failures) {
+  const absolutePath = path.join(rootDir, relativePath);
+  if (!existsSync(absolutePath)) {
+    failures.push(`Missing required file: ${relativePath}`);
+    return '';
+  }
+
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function expectIncludes(text, snippet, label, failures) {
+  if (!text.includes(snippet)) {
+    failures.push(`${label} is missing expected snippet: ${snippet}`);
+  }
+}
+
+function expectNotIncludes(text, snippet, label, failures) {
+  if (text.includes(snippet)) {
+    failures.push(`${label} still contains outdated snippet: ${snippet}`);
+  }
+}
+
+function validatePackageScripts(rootDir, failures) {
+  const packageJsonText = readText(rootDir, 'package.json', failures);
+  if (!packageJsonText) {
+    return;
+  }
+
+  let packageJson;
+  try {
+    packageJson = JSON.parse(packageJsonText);
+  } catch {
+    failures.push('package.json is not valid JSON');
+    return;
+  }
+
+  const docsCheck = packageJson.scripts?.['docs:check'];
+  if (!docsCheck || !docsCheck.includes('validate-docs.js')) {
+    failures.push('package.json scripts.docs:check must include "validate-docs.js"');
+  }
+}
+
+function validateAnalyzeDocs(rootDir, failures) {
+  const readme = readText(rootDir, 'README.md', failures);
+  const cliSource = readText(rootDir, 'src/cli/index.ts', failures);
+
+  if (!readme || !cliSource) {
+    return;
+  }
+
+  const requiredCliSnippets = [
+    ".option('-i, --intent <type>'",
+    ".option('-t, --targets <paths...>'",
+    ".option('-k, --keywords <words...>'",
+    ".option('--include-tests'"
+  ];
+
+  for (const snippet of requiredCliSnippets) {
+    expectIncludes(cliSource, snippet, 'src/cli/index.ts', failures);
+  }
+
+  const requiredReadmeExamples = [
+    'mycodemap analyze -i overview -t src/orchestrator',
+    'mycodemap analyze -i impact -t src/cli/index.ts --include-tests',
+    'mycodemap analyze -i dependency -t src/cli/index.ts',
+    'mycodemap analyze -i search -k UnifiedResult'
+  ];
+
+  for (const example of requiredReadmeExamples) {
+    expectIncludes(readme, example, 'README.md analyze examples', failures);
+  }
+
+  const outdatedReadmeExamples = [
+    'mycodemap analyze "',
+    'mycodemap analyze --intent impact --file',
+    'mycodemap analyze --intent dependency --file',
+    'mycodemap analyze --intent search "'
+  ];
+
+  for (const example of outdatedReadmeExamples) {
+    expectNotIncludes(readme, example, 'README.md analyze examples', failures);
+  }
+}
+
+function validateTestingDocs(rootDir, failures) {
+  const testingRule = readText(rootDir, 'docs/rules/testing.md', failures);
+  const vitestConfig = readText(rootDir, 'vitest.config.ts', failures);
+  const benchmarkConfig = readText(rootDir, 'vitest.benchmark.config.ts', failures);
+
+  if (!testingRule || !vitestConfig || !benchmarkConfig) {
+    return;
+  }
+
+  const sharedSnippets = [
+    "include: ['src/**/*.test.ts']",
+    "exclude: ['node_modules', 'dist', 'refer/**/*.test.ts']",
+    'testTimeout: 10000',
+    'hookTimeout: 10000'
+  ];
+
+  for (const snippet of sharedSnippets) {
+    expectIncludes(vitestConfig, snippet, 'vitest.config.ts', failures);
+    expectIncludes(testingRule, snippet, 'docs/rules/testing.md', failures);
+  }
+
+  expectIncludes(benchmarkConfig, "include: ['refer/benchmark-quality.test.ts']", 'vitest.benchmark.config.ts', failures);
+  expectIncludes(testingRule, '`refer/benchmark-quality.test.ts`', 'docs/rules/testing.md', failures);
+  expectIncludes(testingRule, '`vitest.benchmark.config.ts`', 'docs/rules/testing.md', failures);
+}
+
+function validateGuardrailDocs(rootDir, failures) {
+  const readme = readText(rootDir, 'README.md', failures);
+  const engineeringRule = readText(rootDir, 'docs/rules/engineering-with-codex-openai.md', failures);
+  const validationRule = readText(rootDir, 'docs/rules/validation.md', failures);
+  const ciWorkflow = readText(rootDir, '.github/workflows/ci-gateway.yml', failures);
+  const preCommitHook = readText(rootDir, '.githooks/pre-commit', failures);
+
+  if (readme) {
+    const requiredReadmeGuardrails = [
+      'npm run docs:check',
+      'mycodemap ci check-docs-sync'
+    ];
+
+    for (const snippet of requiredReadmeGuardrails) {
+      expectIncludes(readme, snippet, 'README.md guardrail commands', failures);
+    }
+  }
+
+  if (engineeringRule) {
+    const requiredReferences = [
+      '.githooks/pre-commit',
+      '.githooks/commit-msg',
+      '.github/workflows/ci-gateway.yml',
+      '.github/workflows/publish.yml',
+      'npm run docs:check'
+    ];
+
+    for (const reference of requiredReferences) {
+      expectIncludes(engineeringRule, reference, 'docs/rules/engineering-with-codex-openai.md', failures);
+    }
+  }
+
+  if (validationRule) {
+    expectIncludes(validationRule, 'npm run docs:check', 'docs/rules/validation.md', failures);
+  }
+
+  if (ciWorkflow) {
+    expectIncludes(ciWorkflow, 'run: npm run docs:check', '.github/workflows/ci-gateway.yml', failures);
+    expectIncludes(ciWorkflow, 'run: npm run typecheck', '.github/workflows/ci-gateway.yml', failures);
+    expectIncludes(ciWorkflow, 'run: npm run build', '.github/workflows/ci-gateway.yml', failures);
+    expectIncludes(ciWorkflow, 'run: node dist/cli/index.js ci check-docs-sync', '.github/workflows/ci-gateway.yml', failures);
+    expectIncludes(ciWorkflow, 'node dist/cli/index.js generate', '.github/workflows/ci-gateway.yml', failures);
+  }
+
+  if (preCommitHook) {
+    expectIncludes(preCommitHook, 'npm run docs:check', '.githooks/pre-commit', failures);
+  }
+}
+
+function validateAssistantDocs(rootDir, failures) {
+  const assistantGuide = readText(rootDir, 'docs/AI_ASSISTANT_SETUP.md', failures);
+  const setupGuide = readText(rootDir, 'docs/SETUP_GUIDE.md', failures);
+
+  if (assistantGuide) {
+    const requiredAssistantSnippets = [
+      'npm run docs:check',
+      'mycodemap ci check-docs-sync',
+      'docs/rules/engineering-with-codex-openai.md'
+    ];
+
+    for (const snippet of requiredAssistantSnippets) {
+      expectIncludes(assistantGuide, snippet, 'docs/AI_ASSISTANT_SETUP.md', failures);
+    }
+  }
+
+  if (setupGuide) {
+    const requiredSetupSnippets = [
+      'npm run docs:check',
+      'npm run typecheck',
+      'npx mycodemap ci check-docs-sync',
+      'npx mycodemap ci check-commit-size --range origin/main..HEAD',
+      'npx mycodemap ci assess-risk --threshold=0.7',
+      'npx mycodemap ci check-output-contract --schema-version v1.0.0 --top-k 8 --max-tokens 160',
+      'git diff --exit-code .mycodemap/ai-feed.txt'
+    ];
+
+    for (const snippet of requiredSetupSnippets) {
+      expectIncludes(setupGuide, snippet, 'docs/SETUP_GUIDE.md', failures);
+    }
+  }
+}
+
+function validateDocs(rootDir) {
+  const failures = [];
+
+  validatePackageScripts(rootDir, failures);
+  validateAnalyzeDocs(rootDir, failures);
+  validateTestingDocs(rootDir, failures);
+  validateGuardrailDocs(rootDir, failures);
+  validateAssistantDocs(rootDir, failures);
+
+  if (failures.length > 0) {
+    console.error('ERROR: documentation guardrails failed');
+    for (const failure of failures) {
+      console.error(`- ${failure}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Documentation guardrails passed');
+}
+
+validateDocs(parseRootDir(process.argv.slice(2)));