@mycodemap/mycodemap 0.5.2-beta.1 → 1.9.0

package/scripts/validate-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) {
@@ -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(
@@ -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) {
@@ -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) {
@@ -806,22 +998,29 @@ function validateCliSurfaceDocs(rootDir, failures) {
 
 function validateConfigDocs(rootDir, failures) {
   const readme = 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 +1030,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 +1068,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,6 +1078,34 @@ 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) {
@@ -903,7 +1147,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`'
       ],
       [],
@@ -970,7 +1214,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 +1224,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 +1232,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 +1247,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 +1275,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 +1294,7 @@ function validateGraphStorageDocs(rootDir, failures) {
         '"storage"',
         '"enum": ["filesystem", "sqlite", "memory", "auto"]',
         '"outputPath"',
+        '".mycodemap/storage"',
         '"databasePath"',
         '"autoThresholds"'
       ],
@@ -1347,6 +1592,28 @@ function validateGuardrailDocs(rootDir, failures) {
   }
 }
 
+function validateValidationTruthDocs(rootDir, failures) {
+  const readme = 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);
@@ -1389,6 +1656,7 @@ function validateDocs(rootDir) {
   validateConfigDocs(rootDir, failures);
   validatePluginRuntimeDocs(rootDir, failures);
   validateGraphStorageDocs(rootDir, failures);
+  validateEntryDocGovernance(rootDir, failures);
   validateAnalyzeDocs(rootDir, failures);
   validateHistoryRiskDocs(rootDir, failures);
   validateDesignContractDocs(rootDir, failures);
@@ -1396,6 +1664,7 @@ function validateDocs(rootDir) {
   validateWorkflowAndDiscoveryDocs(rootDir, failures);
   validateProductSpecsDocs(rootDir, failures);
   validateGuardrailDocs(rootDir, failures);
+  validateValidationTruthDocs(rootDir, failures);
   validateAssistantDocs(rootDir, failures);
 
   if (failures.length > 0) {