claudeos-core 2.2.0 → 2.3.1

package/README.zh-CN.md

@@ -69,6 +69,34 @@ ClaudeOS-Core 生成的文档知道你的项目使用 `ApiResponse.ok()`（而
 
 ---
 
+## 生成后质量保证 (v2.3.0)
+
+生成只解决了问题的一半。另一半是 **知道输出是正确的** —— 跨越 10 种输出语言、11 种 stack 模板、以及各种规模的项目。v2.3.0 添加了两个在生成之后运行的确定性验证器,它们不依赖 LLM 自检。
+
+### `claude-md-validator` —— 结构不变式
+
+每个生成的 `CLAUDE.md` 都会对照 25 个结构不变式进行检查,这些不变式只使用语言无关的信号: markdown 语法 (`^## `, `^### `)、不会被翻译的字面文件名 (`decision-log.md`, `failure-patterns.md`)、section 数量、每个 section 的子 section 数量、表格行数。同一个验证器对英语、韩语、日语、越南语、印地语、俄语、西班牙语、中文、法语、德语生成的 `CLAUDE.md` 会产出逐字节相同的判定。
+
+跨语言保证由所有 10 种语言的测试 fixture 验证,其中 6 种语言的坏用例 fixture 会产生完全相同的错误签名。当不变式在越南语项目上失败时,修复方法与在德语项目上失败时完全相同。
+
+### `content-validator [10/10]` —— 路径声明验证与 MANIFEST 一致性
+
+读取所有生成的 `.md` 文件中以反引号括起的路径引用 (`src/...`, `.claude/rules/...`, `claudeos-core/skills/...`) 并对照真实文件系统进行验证。捕捉两类此前没有工具能检测的 LLM 失败:
+
+- **`STALE_PATH`** —— 当 Pass 3 或 Pass 4 捏造出看似合理但不存在的路径时。典型例子: 实际文件是 `routePath.ts`,但因 TypeScript 常量名为 `FEATURE_ROUTE_PATH` 而推断出 `featureRoutePath.ts`; 在多入口项目中从 Vite 约定推断出 `src/main.tsx`; 项目根本没有测试,却从 MSW 文档推断出 `src/__mocks__/handlers.ts`。
+- **`MANIFEST_DRIFT`** —— 当 `claudeos-core/skills/00.shared/MANIFEST.md` 注册了某个 skill 但 `CLAUDE.md §6` 没有提到 (或反之)。它识别出 orchestrator + sub-skills 布局 (其中 `CLAUDE.md §6` 是入口点,`MANIFEST.md` 是完整注册表),并将 sub-skills 判定为通过其父 orchestrator 间接覆盖。
+
+验证器与 `pass3-footer.md` 和 `pass4.md` 中的 prompt 级别预防配对: 记录了具体幻觉类别 (父目录前缀、Vite/MSW/Vitest/Jest/RTL 库约定) 的 anti-pattern 块,以及在 `pass3a-facts.md` 没有具体文件名时把规则限定到目录级别的明确 positive guidance。
+
+### 在任意项目上运行验证
+
+```bash
+npx claudeos-core health     # 所有验证器 —— 单一 go/no-go 判定
+npx claudeos-core lint       # 仅 CLAUDE.md 结构不变式 (任意语言)
+```
+
+---
+
 ## 支持的技术栈
 
 | 技术栈 | 检测方式 | 分析深度 |

package/bin/cli.js

@@ -1,149 +1,153 @@
 #!/usr/bin/env node
-
-/**
- * ClaudeOS-Core — CLI
- *
- * Node.js replacement for bootstrap.sh with cross-platform support.
- * Usage:
- *   npx claudeos-core init --lang ko  ← Run 4-Pass pipeline (Korean output)
- *   npx claudeos-core init            ← Interactive language selection
- *   npx claudeos-core health          ← Run health checker
- *   npx claudeos-core validate        ← Run plan validator (--check)
- *   npx claudeos-core restore         ← Restore from Master Plan
- *   npx claudeos-core refresh         ← Sync disk → Plan
- *   npx claudeos-core memory <sub>    ← L4 memory (compact/score/propose-rules)
- *   npx claudeos-core --help          ← Show help
- *
- * Also works when cloned directly:
- *   node claudeos-core-tools/bin/cli.js init
- */
-
-const path = require("path");
-const { TOOLS_DIR, PROJECT_ROOT, log, run, readFile } = require("./lib/cli-utils");
-const { cmdInit, InitError } = require("./commands/init");
-const { cmdMemory } = require("./commands/memory");
-
-// Set env var so sub-tools (plan-installer, etc.) correctly resolve the project root
-process.env.CLAUDEOS_ROOT = PROJECT_ROOT;
-
-// ─── Command handlers (simple — delegate to sub-tools) ───────────
-function cmdHealth() {
-  run(`node "${path.join(TOOLS_DIR, "health-checker/index.js")}"`);
-}
-
-function cmdValidate() {
-  run(`node "${path.join(TOOLS_DIR, "plan-validator/index.js")}" --check`);
-}
-
-function cmdRestore() {
-  run(`node "${path.join(TOOLS_DIR, "plan-validator/index.js")}" --execute`);
-}
-
-function cmdRefresh() {
-  run(`node "${path.join(TOOLS_DIR, "plan-validator/index.js")}" --refresh`);
-}
-
-// ─── Help ───────────────────────────────────────────────────────
-function showHelp() {
-  log(`
-ClaudeOS-Core — Auto-generate Claude Code documentation from your source code.
-
-Usage:
-  claudeos-core <command>
-
-Commands:
-  init               Run the full 4-Pass pipeline (analyze → merge → generate → memory scaffold)
-  health             Run all verification tools (health checker)
-  validate           Check Plan ↔ disk consistency
-  refresh            Sync disk changes → Master Plan
-  restore            Restore all files from Master Plan
-  memory <sub>       L4 memory:  compact | score | propose-rules
-
-Options:
-  --lang CODE Output language for generated files (required for init)
-              Supported: en, ko, zh-CN, ja, es, vi, hi, ru, fr, de
-              If omitted, interactive selection is shown.
-  --force     Skip resume prompt and start fresh (delete previous results)
-  --help      Show this help message
-  --version   Show version
-
-Examples:
-  npx claudeos-core init --lang ko    # Generate in Korean
-  npx claudeos-core init --lang ja    # Generate in Japanese
-  npx claudeos-core init              # Interactive language selection
-  npx claudeos-core health            # Check everything is consistent
-  npx claudeos-core restore           # Recover from corrupted docs
-`);
-}
-
-// ─── Argument parser ────────────────────────────────────────────
-function parseArgs(argv) {
-  const result = { command: null, lang: null };
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === "--lang" && i + 1 < argv.length) {
-      result.lang = argv[++i];
-    } else if (argv[i].startsWith("--lang=")) {
-      result.lang = argv[i].split("=")[1];
-    } else if (argv[i] === "--force" || argv[i] === "-f") {
-      result.force = true;
-    } else if (argv[i] === "--help" || argv[i] === "-h") {
-      // If we already saw a command (e.g. `memory --help`), let that command
-      // handle --help itself via process.argv. Only promote --help to
-      // top-level when it appears before any command (e.g. `--help` alone or
-      // `--help memory`). This lets `memory --help` show memory's subcommand
-      // help rather than the top-level usage.
-      if (!result.command) result.command = "--help";
-    } else if (argv[i] === "--version" || argv[i] === "-v") {
-      result.command = "--version";
-    } else if (!argv[i].startsWith("-") && !result.command) {
-      result.command = argv[i];
-    }
-  }
-  return result;
-}
-
-// ─── Main ───────────────────────────────────────────────────────
-const args = process.argv.slice(2);
-const parsedArgs = parseArgs(args);
-const command = parsedArgs.command;
-
-if (!command || command === "--help") {
-  showHelp();
-  process.exit(0);
-}
-
-if (command === "--version") {
-  try {
-    const pkg = JSON.parse(
-      readFile(path.join(TOOLS_DIR, "package.json"))
-    );
-    log(`claudeos-core v${pkg.version}`);
-  } catch (e) {
-    log("claudeos-core (version unknown)");
-  }
-  process.exit(0);
-}
-
-const commands = {
-  init: () => cmdInit(parsedArgs),
-  health: cmdHealth,
-  validate: cmdValidate,
-  restore: cmdRestore,
-  refresh: cmdRefresh,
-  memory: () => cmdMemory(parsedArgs),
-};
-
-if (!commands[command]) {
-  log(`Unknown command: ${command}`);
-  log('Run "claudeos-core --help" for usage.');
-  process.exit(1);
-}
-
-Promise.resolve().then(() => commands[command]()).catch((e) => {
-  if (e instanceof InitError) {
-    log(`\n  ❌ ${e.message}\n`);
-  } else {
-    console.error(e.message || e);
-  }
-  process.exit(1);
-});
+
+/**
+ * ClaudeOS-Core — CLI
+ *
+ * Node.js replacement for bootstrap.sh with cross-platform support.
+ * Usage:
+ *   npx claudeos-core init --lang ko  ← Run 4-Pass pipeline (Korean output)
+ *   npx claudeos-core init            ← Interactive language selection
+ *   npx claudeos-core health          ← Run health checker
+ *   npx claudeos-core validate        ← Run plan validator (--check)
+ *   npx claudeos-core restore         ← Restore from Master Plan
+ *   npx claudeos-core refresh         ← Sync disk → Plan
+ *   npx claudeos-core memory <sub>    ← L4 memory (compact/score/propose-rules)
+ *   npx claudeos-core --help          ← Show help
+ *
+ * Also works when cloned directly:
+ *   node claudeos-core-tools/bin/cli.js init
+ */
+
+const path = require("path");
+const { TOOLS_DIR, PROJECT_ROOT, log, run, readFile } = require("./lib/cli-utils");
+const { cmdInit, InitError } = require("./commands/init");
+const { cmdMemory } = require("./commands/memory");
+const { cmdLint } = require("./commands/lint");
+
+// Set env var so sub-tools (plan-installer, etc.) correctly resolve the project root
+process.env.CLAUDEOS_ROOT = PROJECT_ROOT;
+
+// ─── Command handlers (simple — delegate to sub-tools) ───────────
+function cmdHealth() {
+  run(`node "${path.join(TOOLS_DIR, "health-checker/index.js")}"`);
+}
+
+function cmdValidate() {
+  run(`node "${path.join(TOOLS_DIR, "plan-validator/index.js")}" --check`);
+}
+
+function cmdRestore() {
+  run(`node "${path.join(TOOLS_DIR, "plan-validator/index.js")}" --execute`);
+}
+
+function cmdRefresh() {
+  run(`node "${path.join(TOOLS_DIR, "plan-validator/index.js")}" --refresh`);
+}
+
+// ─── Help ───────────────────────────────────────────────────────
+function showHelp() {
+  log(`
+ClaudeOS-Core — Auto-generate Claude Code documentation from your source code.
+
+Usage:
+  claudeos-core <command>
+
+Commands:
+  init               Run the full 4-Pass pipeline (analyze → merge → generate → memory scaffold)
+  lint               Validate CLAUDE.md structure (language-invariant post-generation check)
+  health             Run all verification tools (health checker)
+  validate           Check Plan ↔ disk consistency
+  refresh            Sync disk changes → Master Plan
+  restore            Restore all files from Master Plan
+  memory <sub>       L4 memory:  compact | score | propose-rules
+
+Options:
+  --lang CODE Output language for generated files (required for init)
+              Supported: en, ko, zh-CN, ja, es, vi, hi, ru, fr, de
+              If omitted, interactive selection is shown.
+  --force     Skip resume prompt and start fresh (delete previous results)
+  --help      Show this help message
+  --version   Show version
+
+Examples:
+  npx claudeos-core init --lang ko    # Generate in Korean
+  npx claudeos-core init --lang ja    # Generate in Japanese
+  npx claudeos-core init              # Interactive language selection
+  npx claudeos-core lint              # Validate CLAUDE.md structure (any language)
+  npx claudeos-core health            # Check everything is consistent
+  npx claudeos-core restore           # Recover from corrupted docs
+`);
+}
+
+// ─── Argument parser ────────────────────────────────────────────
+function parseArgs(argv) {
+  const result = { command: null, lang: null };
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--lang" && i + 1 < argv.length) {
+      result.lang = argv[++i];
+    } else if (argv[i].startsWith("--lang=")) {
+      result.lang = argv[i].split("=")[1];
+    } else if (argv[i] === "--force" || argv[i] === "-f") {
+      result.force = true;
+    } else if (argv[i] === "--help" || argv[i] === "-h") {
+      // If we already saw a command (e.g. `memory --help`), let that command
+      // handle --help itself via process.argv. Only promote --help to
+      // top-level when it appears before any command (e.g. `--help` alone or
+      // `--help memory`). This lets `memory --help` show memory's subcommand
+      // help rather than the top-level usage.
+      if (!result.command) result.command = "--help";
+    } else if (argv[i] === "--version" || argv[i] === "-v") {
+      result.command = "--version";
+    } else if (!argv[i].startsWith("-") && !result.command) {
+      result.command = argv[i];
+    }
+  }
+  return result;
+}
+
+// ─── Main ───────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const parsedArgs = parseArgs(args);
+const command = parsedArgs.command;
+
+if (!command || command === "--help") {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === "--version") {
+  try {
+    const pkg = JSON.parse(
+      readFile(path.join(TOOLS_DIR, "package.json"))
+    );
+    log(`claudeos-core v${pkg.version}`);
+  } catch (e) {
+    log("claudeos-core (version unknown)");
+  }
+  process.exit(0);
+}
+
+const commands = {
+  init: () => cmdInit(parsedArgs),
+  lint: () => cmdLint(parsedArgs),
+  health: cmdHealth,
+  validate: cmdValidate,
+  restore: cmdRestore,
+  refresh: cmdRefresh,
+  memory: () => cmdMemory(parsedArgs),
+};
+
+if (!commands[command]) {
+  log(`Unknown command: ${command}`);
+  log('Run "claudeos-core --help" for usage.');
+  process.exit(1);
+}
+
+Promise.resolve().then(() => commands[command]()).catch((e) => {
+  if (e instanceof InitError) {
+    log(`\n  ❌ ${e.message}\n`);
+  } else {
+    console.error(e.message || e);
+  }
+  process.exit(1);
+});