@mycodemap/mycodemap 0.5.2-beta.1 → 2.0.0

package/scripts/validate-docs.js

@@ -1,7 +1,7 @@
 // [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 { existsSync, readFileSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { collectAnalyzeDocSyncFailures } from './sync-analyze-docs.js';
@@ -46,6 +46,39 @@ function expectNotIncludes(text, snippet, label, failures) {
   }
 }
 
+function expectNoCommandSurface(text, label, forbiddenSnippets, failures) {
+  if (!text) {
+    return;
+  }
+
+  for (const snippet of forbiddenSnippets) {
+    if (text.includes(snippet)) {
+      failures.push(`[entry-doc ghost-command] ${label} should stay routing-only, but contains command snippet: ${snippet}`);
+    }
+  }
+}
+
+function expectNoPolicyDuplication(text, label, forbiddenSnippets, failures) {
+  if (!text) {
+    return;
+  }
+
+  for (const snippet of forbiddenSnippets) {
+    if (text.includes(snippet)) {
+      failures.push(`[entry-doc duplicate-policy] ${label} duplicates governance policy that should stay in AGENTS.md or live rules: ${snippet}`);
+    }
+  }
+}
+
+function expectReferencedPaths(rootDir, label, references, failures) {
+  for (const reference of references) {
+    const absolutePath = path.join(rootDir, reference);
+    if (!existsSync(absolutePath)) {
+      failures.push(`[entry-doc ghost-route] ${label} references missing path: ${reference}`);
+    }
+  }
+}
+
 function validateSnippets(text, label, requiredSnippets, outdatedSnippets, failures) {
   if (!text) {
     return;
@@ -60,6 +93,165 @@ function validateSnippets(text, label, requiredSnippets, outdatedSnippets, failu
   }
 }
 
+function validateEntryDocGovernance(rootDir, failures) {
+  const agents = readText(rootDir, 'AGENTS.md', failures);
+  const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
+  const claudeAdapter = readText(rootDir, '.claude/CLAUDE.md', failures);
+  const rulesIndex = readText(rootDir, 'docs/rules/README.md', failures);
+
+  validateSnippets(
+    agents,
+    'AGENTS.md entry-doc authority baseline',
+    [
+      '`AGENTS.md = constitution` / `CLAUDE.md = router` / `.claude/CLAUDE.md = Claude adapter`',
+      '本文件只保留仓库级治理协议；若某条细则在 live doc 已定权，这里只保留原则与路由，不重复正文。'
+    ],
+    [],
+    failures
+  );
+
+  validateSnippets(
+    claudeGuide,
+    'CLAUDE.md router baseline',
+    [
+      '本文件只回答三件事：**谁定权、下一步去哪读、规则变更时该改哪份文档**。',
+      '它不是执行手册、命令速查、验证清单或交付 checklist。'
+    ],
+    [
+      'AI 执行手册',
+      '最小执行手册',
+      'Claude/Codex 执行手册'
+    ],
+    failures
+  );
+
+  validateSnippets(
+    claudeAdapter,
+    '.claude/CLAUDE.md adapter baseline',
+    [
+      'Claude Code 会自动读取本文件；它只负责把 Claude 连接到仓库里的**共享真相**。',
+      '本文件不是执行手册，也不是第二套规则入口。'
+    ],
+    [
+      'AI 执行手册',
+      '最小执行手册',
+      'Claude/Codex 执行手册',
+      'Claude 第二手册'
+    ],
+    failures
+  );
+
+  validateSnippets(
+    rulesIndex,
+    'docs/rules/README.md routing baseline',
+    [
+      '入口角色约束：`AGENTS.md` 定权，根 `CLAUDE.md` 只负责把你路由到这里或其他 live docs；规则正文仍以本目录各文件为准。'
+    ],
+    [],
+    failures
+  );
+
+  expectNoCommandSurface(
+    claudeGuide,
+    'CLAUDE.md',
+    ['npm run ', 'node dist/cli/index.js', 'mycodemap ', 'rtk ', 'python3 scripts/', '$gsd-'],
+    failures
+  );
+  expectNoCommandSurface(
+    claudeAdapter,
+    '.claude/CLAUDE.md',
+    ['npm run ', 'node dist/cli/index.js', 'mycodemap ', 'rtk ', 'python3 scripts/', '$gsd-'],
+    failures
+  );
+
+  expectNoPolicyDuplication(
+    claudeGuide,
+    'CLAUDE.md',
+    [
+      '## 3.1 任务分级与自主权边界（Harness 规范）',
+      '## 5. 证据协议',
+      '## 5.1 可信度自评要求（Harness 规范）',
+      '## 7.1 代码生成红线（Harness 规范）',
+      '## 8. 验证与失败预演'
+    ],
+    failures
+  );
+  expectNoPolicyDuplication(
+    claudeAdapter,
+    '.claude/CLAUDE.md',
+    [
+      '## 3.1 任务分级与自主权边界（Harness 规范）',
+      '## 5. 证据协议',
+      '## 5.1 可信度自评要求（Harness 规范）',
+      '## 7.1 代码生成红线（Harness 规范）',
+      '## 8. 验证与失败预演'
+    ],
+    failures
+  );
+
+  expectReferencedPaths(
+    rootDir,
+    'CLAUDE.md',
+    [
+      'AGENTS.md',
+      '.claude/CLAUDE.md',
+      'docs/rules/README.md',
+      'docs/rules/engineering-with-codex-openai.md',
+      'docs/rules/validation.md',
+      'docs/rules/architecture-guardrails.md',
+      'docs/rules/code-quality-redlines.md',
+      'docs/rules/testing.md',
+      'docs/rules/release.md',
+      'AI_GUIDE.md',
+      'ARCHITECTURE.md',
+      'docs/ai-guide'
+    ],
+    failures
+  );
+  expectReferencedPaths(
+    rootDir,
+    '.claude/CLAUDE.md',
+    [
+      'AGENTS.md',
+      'CLAUDE.md',
+      'docs/rules/engineering-with-codex-openai.md',
+      'docs/rules/validation.md',
+      'AI_GUIDE.md',
+      'ARCHITECTURE.md'
+    ],
+    failures
+  );
+  expectReferencedPaths(
+    rootDir,
+    'docs/rules/README.md',
+    [
+      'docs/rules/code-quality-redlines.md',
+      'docs/rules/architecture-guardrails.md',
+      'docs/rules/testing.md',
+      'docs/rules/validation.md',
+      'docs/rules/engineering-with-codex-openai.md',
+      'docs/rules/release.md',
+      'docs/rules/deployment.md',
+      'docs/rules/pre-release-checklist.md'
+    ],
+    failures
+  );
+
+  if (
+    claudeGuide &&
+    (!claudeGuide.includes('AGENTS.md') || !claudeGuide.includes('docs/rules/README.md'))
+  ) {
+    failures.push('[entry-doc authority-routing] CLAUDE.md no longer routes readers to AGENTS.md and docs/rules/README.md');
+  }
+
+  if (
+    claudeAdapter &&
+    (!claudeAdapter.includes('AGENTS.md') || !claudeAdapter.includes('CLAUDE.md'))
+  ) {
+    failures.push('[entry-doc authority-routing] .claude/CLAUDE.md no longer points Claude back to AGENTS.md and root CLAUDE.md');
+  }
+}
+
 function validatePackageScripts(rootDir, failures) {
   const packageJsonText = readText(rootDir, 'package.json', failures);
   if (!packageJsonText) {
@@ -81,7 +273,7 @@ function validatePackageScripts(rootDir, failures) {
 }
 
 function validateAnalyzeDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -195,7 +387,7 @@ function validateAnalyzeDocs(rootDir, failures) {
     failures
   );
 
-  // NOTE: CLAUDE.md 已演进为执行手册（路由层），analyze 命令指南已移至 AI_GUIDE.md / docs/ai-guide/
+  // NOTE: CLAUDE.md 已演进为入口路由，analyze 命令指南已移至 AI_GUIDE.md / docs/ai-guide/
   // 相关检查已下放至 AI_GUIDE.md 与 docs/ai-guide/*.md 的 validateSnippets 中
 
   validateSnippets(
@@ -218,7 +410,7 @@ function validateAnalyzeDocs(rootDir, failures) {
 }
 
 function validateHistoryRiskDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -274,7 +466,7 @@ function validateHistoryRiskDocs(rootDir, failures) {
     );
   }
 
-  // NOTE: CLAUDE.md 已演进为执行手册（路由层），history 风险基线已移至 AI_GUIDE.md / docs/ai-guide/
+  // NOTE: CLAUDE.md 已演进为入口路由，history 风险基线已移至 AI_GUIDE.md / docs/ai-guide/
   // 相关检查已下放至 AI_GUIDE.md 与 docs/ai-guide/*.md 的 validateSnippets 中
 
   if (commandsGuide) {
@@ -321,7 +513,7 @@ function validateHistoryRiskDocs(rootDir, failures) {
 }
 
 function validateDesignContractDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -437,7 +629,7 @@ function validateDesignContractDocs(rootDir, failures) {
     );
   }
 
-  // NOTE: CLAUDE.md 已演进为执行手册（路由层），design 检索指南已移至 AI_GUIDE.md / docs/ai-guide/
+  // NOTE: CLAUDE.md 已演进为入口路由，design 检索指南已移至 AI_GUIDE.md / docs/ai-guide/
   // 相关检查已下放至 AI_GUIDE.md 与 docs/ai-guide/*.md 的 validateSnippets 中
 
   if (commandsGuide) {
@@ -643,8 +835,104 @@ function validateDesignContractDocs(rootDir, failures) {
   }
 }
 
+function validateNpmScriptsAreReal(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 — cannot validate npm scripts');
+    return;
+  }
+
+  const scripts = packageJson.scripts;
+  if (!scripts || typeof scripts !== 'object') {
+    return;
+  }
+
+  /** Pattern matching echo stubs like: echo 'dependency-cruiser not installed, run: npm i -D dependency-cruiser' */
+  const ECHO_STUB_PATTERN = /^echo\s+['"].*not installed/i;
+
+  // Check all referenced npm scripts in docs are real (not echo stubs)
+  const docsDir = path.join(rootDir, 'docs');
+  const githubDir = path.join(rootDir, '.github');
+  const npmRunPattern = /npm\s+run\s+([a-zA-Z0-9:_-]+)/g;
+
+  function scanFileForNpmRun(filePath, label) {
+    if (!existsSync(filePath)) {
+      return;
+    }
+
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      return;
+    }
+
+    let match;
+    while ((match = npmRunPattern.exec(content)) !== null) {
+      const scriptName = match[1].replace(/[.,;:!?`'"()\[\]{}]+$/, '');
+      // Skip known npm lifecycle scripts that don't need to be in package.json
+      const npmLifecycleScripts = new Set([
+        'postinstall', 'preinstall', 'prepare', 'prepublish', 'prepublishOnly',
+        'prerestart', 'postrestart', 'prestart', 'poststart', 'prestop', 'poststop',
+        'pretest', 'posttest', 'preversion', 'postversion',
+      ]);
+      if (npmLifecycleScripts.has(scriptName)) {
+        continue;
+      }
+
+      // Skip if not a defined script
+      if (!(scriptName in scripts)) {
+        failures.push(`[docs-script-ghost] ${label} references undefined npm script: "npm run ${scriptName}"`);
+        continue;
+      }
+
+      const scriptValue = scripts[scriptName];
+      if (typeof scriptValue === 'string' && ECHO_STUB_PATTERN.test(scriptValue)) {
+        failures.push(`[docs-script-stub] ${label} references npm script "${scriptName}" which is an echo stub, not a real command`);
+      }
+    }
+  }
+
+  function scanDirectory(dirPath, labelPrefix) {
+    if (!existsSync(dirPath)) {
+      return;
+    }
+
+    // Walk directory recursively
+    function walk(currentPath, relativePath) {
+      const items = readdirSync(currentPath, { withFileTypes: true });
+      for (const item of items) {
+        const itemPath = path.join(currentPath, item.name);
+        const itemRelPath = path.join(relativePath, item.name);
+        if (item.isDirectory()) {
+          // Skip historical artifact directories
+          if (item.name === 'exec-plans' || item.name === 'ideation' || item.name === 'references' || item.name === 'archive') {
+            continue;
+          }
+          walk(itemPath, itemRelPath);
+        } else if (item.isFile() && item.name.endsWith('.md')) {
+          scanFileForNpmRun(itemPath, `${labelPrefix}/${itemRelPath}`);
+        }
+      }
+    }
+    walk(dirPath, '');
+  }
+
+  scanDirectory(docsDir, 'docs');
+  scanDirectory(githubDir, '.github');
+  // Note: docs/exec-plans/ and docs/ideation/ contain historical artifacts
+  // that reference scripts from their time period — skip them
+}
+
 function validatePositioningBaselineDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const aiGuideIndex = readText(rootDir, 'docs/ai-guide/README.md', failures);
   const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
@@ -652,7 +940,7 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 
   if (readme) {
     const requiredReadmeSnippets = [
-      'AI-first 代码地图工具',
+      'AI-Native',
       'AI/Agent 是主要消费者',
       '`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。'
     ];
@@ -671,8 +959,8 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 
   if (aiGuide) {
     const requiredAiGuideSnippets = [
-      'CodeMap 是一个 AI-first 代码地图工具',
-      '当前 CLI 过渡现实',
+      'CodeMap 是一个 AI-Native 优先',
+      'JSON/NDJSON 默认输出',
       '`Server Layer` 是内部架构层，不等于公共 `mycodemap server` 命令',
       '后者已从 public CLI 移除'
     ];
@@ -684,7 +972,7 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 
   if (aiGuideIndex) {
     const requiredIndexSnippets = [
-      'AI-first 代码地图工具',
+      'AI-Native 优先、人类友好的代码架构治理基础设施',
       'AI/Agent 是主要消费者',
       '`server`、`watch`、`report`、`logs` 已从 public CLI 移除'
     ];
@@ -717,7 +1005,7 @@ function validatePositioningBaselineDocs(rootDir, failures) {
 }
 
 function validateCliSurfaceDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const aiGuideIndex = readText(rootDir, 'docs/ai-guide/README.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -805,23 +1093,30 @@ function validateCliSurfaceDocs(rootDir, failures) {
 }
 
 function validateConfigDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
+  const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const setupGuide = readText(rootDir, 'docs/SETUP_GUIDE.md', failures);
   const assistantGuide = readText(rootDir, 'docs/AI_ASSISTANT_SETUP.md', failures);
+  const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
+  const quickstartGuide = readText(rootDir, 'docs/ai-guide/QUICKSTART.md', failures);
 
   if (readme) {
     validateSnippets(
       readme,
       'README.md config contract',
       [
-        '执行后会在项目根目录生成 `mycodemap.config.json` 配置文件。',
-        '通过 `mycodemap init` 生成的 `mycodemap.config.json` 配置文件支持以下选项：',
+        '执行后会收敛 `.mycodemap/config.json`，并把 machine-readable receipt 写入 `.mycodemap/status/init-last.json`。',
+        '`init` 还会同步 `.mycodemap/hooks/` 与 `.mycodemap/rules/`；但不会自动改写团队自有的 `CLAUDE.md` / `AGENTS.md`，只会在 receipt 中输出可复制片段。',
+        '通过 `mycodemap init` 收敛的 canonical 配置文件是 `.mycodemap/config.json`',
         '"$schema": "https://mycodemap.dev/schema/config.json"',
         '"mode": "hybrid"',
         '"plugins": {',
+        '"outputPath": ".mycodemap/storage"',
         '| `plugins.builtInPlugins` | `boolean` | 是否启用内置插件 | `true` |'
       ],
       [
+        '执行后会在项目根目录生成 `mycodemap.config.json` 配置文件。',
+        '通过 `mycodemap init` 生成的 `mycodemap.config.json` 配置文件支持以下选项：',
         '执行后会在项目根目录生成 `codemap.config.json` 配置文件。',
         '通过 `codemap init` 生成的 `codemap.config.json` 配置文件支持以下选项：',
         '"$schema": "https://codemap.dev/schema.json"',
@@ -831,18 +1126,33 @@ function validateConfigDocs(rootDir, failures) {
     );
   }
 
+  if (aiGuide) {
+    validateSnippets(
+      aiGuide,
+      'AI_GUIDE.md init contract',
+      [
+        '| "需要先把项目初始化到 canonical `.mycodemap/` 工作区" | `init --interactive` → 确认 receipt → `init --yes` |'
+      ],
+      [],
+      failures
+    );
+  }
+
   if (setupGuide) {
     validateSnippets(
       setupGuide,
       'docs/SETUP_GUIDE.md config contract',
       [
-        '生成的配置文件 `mycodemap.config.json`：',
+        '执行后会收敛 canonical 配置 `.mycodemap/config.json`，并把 receipt 写入 `.mycodemap/status/init-last.json`。',
+        '生成的 canonical 配置文件 `.mycodemap/config.json`：',
         '"include": ["src/**/*.ts"]',
         '"watch": false',
         '"plugins": {',
+        '"outputPath": ".mycodemap/storage"',
         '| `plugins.debug` | boolean | `false` | 是否输出插件调试日志 |'
       ],
       [
+        '会询问以下问题：',
         '"include": ["src/**/*"]'
       ],
       failures
@@ -854,7 +1164,9 @@ function validateConfigDocs(rootDir, failures) {
       assistantGuide,
       'docs/AI_ASSISTANT_SETUP.md config contract',
       [
-        '- `mycodemap.config.json` - CodeMap 配置文件'
+        '- `.mycodemap/config.json` - CodeMap canonical 配置文件',
+        '- `.mycodemap/status/init-last.json` - init receipt / managed asset ledger',
+        '- `.mycodemap/rules/` - 通用 AI guardrails rules bundle（需手动引用到 `CLAUDE.md` / `AGENTS.md`）'
       ],
       [
         '- `codemap.config.json` - CodeMap 配置文件'
@@ -862,10 +1174,38 @@ function validateConfigDocs(rootDir, failures) {
       failures
     );
   }
+
+  if (commandsGuide) {
+    validateSnippets(
+      commandsGuide,
+      'docs/ai-guide/COMMANDS.md init contract',
+      [
+        '### init - 收敛项目状态',
+        '`init` 会收敛 `.mycodemap/config.json`、`.mycodemap/status/init-last.json`、`.mycodemap/hooks/` 与 `.mycodemap/rules/`',
+        '`init` 不会自动改写 `CLAUDE.md` 或 `AGENTS.md`，只会输出可复制的 rules 引用片段'
+      ],
+      [],
+      failures
+    );
+  }
+
+  if (quickstartGuide) {
+    validateSnippets(
+      quickstartGuide,
+      'docs/ai-guide/QUICKSTART.md init contract',
+      [
+        'node dist/cli/index.js init --interactive',
+        'node dist/cli/index.js init --yes',
+        '`init` 的 receipt 会把 `done`、`manual action`、`conflict`、`skipped` 分开显示'
+      ],
+      [],
+      failures
+    );
+  }
 }
 
 function validatePluginRuntimeDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
   const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
@@ -903,7 +1243,7 @@ function validatePluginRuntimeDocs(rootDir, failures) {
       commandsGuide,
       'docs/ai-guide/COMMANDS.md plugin runtime contract',
       [
-        '`generate` 不提供独立 `--plugin` flags；插件通过 `mycodemap.config.json` 的 `plugins` 段声明。',
+        '`generate` 不提供独立 `--plugin` flags；插件通过 `.mycodemap/config.json` 的 `plugins` 段声明。',
         '`AI_MAP.md` 会增加 `Plugin Summary`，`codemap.json` 会增加 `pluginReport`'
       ],
       [],
@@ -940,7 +1280,7 @@ function validatePluginRuntimeDocs(rootDir, failures) {
 }
 
 function validateGraphStorageDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const claudeGuide = readText(rootDir, 'CLAUDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
@@ -970,7 +1310,7 @@ function validateGraphStorageDocs(rootDir, failures) {
       aiGuide,
       'AI_GUIDE.md graph storage contract',
       [
-        '| "需要切换/排查图存储后端" | 编辑 `mycodemap.config.json.storage` → 运行 `generate` / `export` |',
+        '| "需要切换/排查图存储后端" | 编辑 `.mycodemap/config.json` 的 `storage` 段 → 运行 `generate` / `export` |',
         '`generate` 会写入配置的图存储后端；`export` 与内部 `Server Layer` handler 会读取同一份后端数据。',
         '`neo4j` 与 `kuzudb` 已不再是正式支持的 backend；旧配置会暴露显式迁移错误，不会静默 fallback。',
         '`storage.type = "auto"` 当前优先选择 `sqlite`；若运行时缺少 `better-sqlite3` 或 Node.js `<20` 导致 SQLite 不可用，则 warning 后回退到 `filesystem`。'
@@ -980,7 +1320,7 @@ function validateGraphStorageDocs(rootDir, failures) {
     );
   }
 
-  // NOTE: CLAUDE.md 已演进为执行手册（路由层），graph storage 合约已移至 AI_GUIDE.md / docs/ai-guide/
+  // NOTE: CLAUDE.md 已演进为入口路由，graph storage 合约已移至 AI_GUIDE.md / docs/ai-guide/
   // 相关检查已下放至 AI_GUIDE.md 与 docs/ai-guide/*.md 的 validateSnippets 中
 
   if (commandsGuide) {
@@ -988,8 +1328,8 @@ function validateGraphStorageDocs(rootDir, failures) {
       commandsGuide,
       'docs/ai-guide/COMMANDS.md graph storage contract',
       [
-        '`generate` 会读取 `mycodemap.config.json.storage`，并把 CodeGraph 写入所选后端。',
-        '`export json|graphml|dot` 会从 `mycodemap.config.json.storage` 指定的后端读取 CodeGraph。',
+        '`generate` 会读取 `.mycodemap/config.json` 的 `storage` 段，并把 CodeGraph 写入所选后端。',
+        '`export json|graphml|dot` 会从 `.mycodemap/config.json` 的 `storage` 段指定后端读取 CodeGraph。',
         '图存储后端收口不等于重新开放公共 `mycodemap server` 产品面；`Server Layer` 仍是内部层。'
       ],
       [],
@@ -1003,7 +1343,7 @@ function validateGraphStorageDocs(rootDir, failures) {
       'docs/ai-guide/QUICKSTART.md graph storage contract',
       [
         'stdout 还会显示当前写入的 `MVP3 Storage (...)`',
-        '| "需要切换/排查图存储后端" | 编辑 `mycodemap.config.json.storage` 后运行 `generate` | `export json` 验证是否能从同一 backend 读回 | 文本 + 机器可读 |'
+        '| "需要切换/排查图存储后端" | 编辑 `.mycodemap/config.json` 的 `storage` 段后运行 `generate` | `export json` 验证是否能从同一 backend 读回 | 文本 + 机器可读 |'
       ],
       [],
       failures
@@ -1031,7 +1371,7 @@ function validateGraphStorageDocs(rootDir, failures) {
       validationRule,
       'docs/rules/validation.md graph storage guardrail',
       [
-        '若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器',
+        '若改动涉及 `.mycodemap/config.json` 的 `storage` 段或图数据库适配器',
         'schema / README / AI 文档没同步',
         '旧的 `neo4j` / `kuzudb` 配置已经不受支持，但文档还把它写成正式 backend',
         'Node.js `>=20`',
@@ -1050,6 +1390,7 @@ function validateGraphStorageDocs(rootDir, failures) {
         '"storage"',
         '"enum": ["filesystem", "sqlite", "memory", "auto"]',
         '"outputPath"',
+        '".mycodemap/storage"',
         '"databasePath"',
         '"autoThresholds"'
       ],
@@ -1086,7 +1427,7 @@ function validateTestingDocs(rootDir, failures) {
 }
 
 function validateWorkflowAndDiscoveryDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
   const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
   const commandsGuide = readText(rootDir, 'docs/ai-guide/COMMANDS.md', failures);
   const outputGuide = readText(rootDir, 'docs/ai-guide/OUTPUT.md', failures);
@@ -1286,7 +1627,7 @@ function validateProductSpecsDocs(rootDir, failures) {
 }
 
 function validateGuardrailDocs(rootDir, failures) {
-  const readme = readText(rootDir, 'README.md', failures);
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || 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);
@@ -1347,6 +1688,28 @@ function validateGuardrailDocs(rootDir, failures) {
   }
 }
 
+function validateValidationTruthDocs(rootDir, failures) {
+  const readme = readText(rootDir, 'README.zh-CN.md', failures) || readText(rootDir, 'README.md', failures);
+  const aiGuide = readText(rootDir, 'AI_GUIDE.md', failures);
+  const validationRule = readText(rootDir, 'docs/rules/validation.md', failures);
+  const engineeringRule = readText(rootDir, 'docs/rules/engineering-with-codex-openai.md', failures);
+  const requiredTruthSnippets = [
+    '文档/入口变更先跑 `npm run docs:check`。',
+    '统一 docs/AI guardrail 入口：`node dist/cli/index.js ci check-docs-sync`（产品命令等价于 `mycodemap ci check-docs-sync`）。',
+    'repo-local rules 预检：`python3 scripts/validate-rules.py code --report-only` 只报告，不阻断。',
+    'CI / PR 超窗、fallback 或 false-positive 漂移时，`warn-only / fallback` 不是 hard gate success。'
+  ];
+
+  for (const [label, text] of [
+    ['README.md validation quick truth', readme],
+    ['AI_GUIDE.md validation quick truth', aiGuide],
+    ['docs/rules/validation.md validation quick truth', validationRule],
+    ['docs/rules/engineering-with-codex-openai.md validation quick truth', engineeringRule]
+  ]) {
+    validateSnippets(text, label, requiredTruthSnippets, [], failures);
+  }
+}
+
 function validateAssistantDocs(rootDir, failures) {
   const assistantGuide = readText(rootDir, 'docs/AI_ASSISTANT_SETUP.md', failures);
   const setupGuide = readText(rootDir, 'docs/SETUP_GUIDE.md', failures);
@@ -1384,11 +1747,13 @@ function validateDocs(rootDir) {
   const failures = [];
 
   validatePackageScripts(rootDir, failures);
+  validateNpmScriptsAreReal(rootDir, failures);
   validatePositioningBaselineDocs(rootDir, failures);
   validateCliSurfaceDocs(rootDir, failures);
   validateConfigDocs(rootDir, failures);
   validatePluginRuntimeDocs(rootDir, failures);
   validateGraphStorageDocs(rootDir, failures);
+  validateEntryDocGovernance(rootDir, failures);
   validateAnalyzeDocs(rootDir, failures);
   validateHistoryRiskDocs(rootDir, failures);
   validateDesignContractDocs(rootDir, failures);
@@ -1396,6 +1761,7 @@ function validateDocs(rootDir) {
   validateWorkflowAndDiscoveryDocs(rootDir, failures);
   validateProductSpecsDocs(rootDir, failures);
   validateGuardrailDocs(rootDir, failures);
+  validateValidationTruthDocs(rootDir, failures);
   validateAssistantDocs(rootDir, failures);
 
   if (failures.length > 0) {