soloforge 1.4.16 → 2.0.0

package/dist/bin/soloforge.js

@@ -1,29 +1,42 @@
 #!/usr/bin/env node
-import crypto from "node:crypto";
-import fss from "node:fs";
-import path from "node:path";
-import { resolveProjectConfig, getProjectKnowledgeDir, getGlobalPatternsDir } from "../knowledge/loader.js";
-import { generateHooksConfig } from "../adapters/claude_code/hooks.js";
-import { generateClaudeMd } from "../adapters/claude_code/hooks.js";
-import { generateTraeRules } from "../adapters/trae/trae_rules.js";
-import { generateTraeMcpConfig } from "../adapters/trae/trae_config.js";
-import { generateCodexMcpConfig, generateCodexHooksConfig } from "../adapters/codex/codex_config.js";
-import { generateCodexAgentsMd } from "../adapters/codex/codex_rules.js";
-import { buildHookAdditionalContext } from "../adapters/claude_code/pre_prompt_contract.js";
-import { detectFingerprint, generateConfigDraft, validateConfigDraft, generateConfigEvidence, canAutoWrite, parseBlueprint, generateBlueprintEvidence, } from "../engine/zero_config_init.js";
-import YAML from "yaml";
-import { cmdConfigResolve, cmdConfigExplain, cmdConfigConfirm, cmdConfigUnset, cmdConfigRepair, loadConfigEvidenceEntries, } from "./config_commands.js";
-import { resolveCurrentProjectConfigReports, validateConfigPrecedence, } from "../engine/config_precedence_contract.js";
-import { isReadForbidden } from "../engine/privacy_secret_contract.js";
-import { routeIntent } from "../engine/intent_router.js";
-import { debugLog, debug, userInfo, userWarn, userError, internalWarn, jsonSafeError, initLoggerFromEnv } from "../engine/logger.js";
-import { auditControlPlaneProject, isSoloforgeStateBypassCommand } from "../engine/control_plane_contract.js";
-import { getDesignLifecycleArtifactPaths } from "../engine/design_lifecycle_contract.js";
-import { isSameOrDescendantPath } from "../engine/path_scope_utils.js";
-const command = process.argv[2];
-const args = process.argv.slice(3);
+import { initLoggerFromEnv, userInfo } from "../engine/core/logger.js";
+import { cmdConfigSet, cmdConfigShow, cmdConfigCheck, cmdConfigExport, cmdConfigExplain, cmdConfigUnset, } from "./config_commands.js";
+import { command, args } from "./args.js";
+import { EXIT } from "../engine/core/exit_codes.js";
+import { cmdInitAuto, cmdInitBlueprint, cmdInit } from "./commands/init.js";
+import { cmdGenerateHooks, cmdGenerateClaudeMd, cmdGenerateTrae, cmdGenerateCodex } from "./commands/hooks.js";
+import { cmdCheckWrite } from "./commands/check_write.js";
+import { cmdCheckBash, cmdPostBash } from "./commands/check_bash.js";
+import { cmdDoctor, cmdPrePrompt, cmdValidate, cmdValidateMechanisms } from "./commands/validate.js";
+import { cmdAuditTemplateMechanisms, cmdAuditDesignArtifacts, cmdUpgradeDesignArtifacts, cmdAuditTemplateVisibility, cmdAuditProjectKnowledge, cmdValidateKnowledge, } from "./commands/audit.js";
+import { cmdSyncTemplates, cmdSyncAdapters, cmdMigrate, cmdValidateReleaseGate, cmdValidateNewIssue, cmdValidateFoundation, } from "./commands/sync.js";
+import { cmdStatus, cmdNext, cmdStage, cmdCleanup, cmdVersion } from "./commands/status.js";
+import { cmdAnalyze } from "./commands/analyze.js";
+import { cmdModify } from "./commands/modify.js";
+import { cmdReview } from "./commands/review.js";
+import { cmdBrainstorm, cmdFirstPrinciples, cmdReasoningLog } from "./commands/reasoning.js";
 async function main() {
     initLoggerFromEnv();
+    // ── --help / -h 支持 ──
+    if (command === "--help" || command === "-h" || command === "help") {
+        userInfo(`SoloForge CLI
+
+用法: soloforge <命令>
+
+常用命令:
+  init                在当前项目初始化 .soloforge/
+  status              显示当前项目的 SoloForge 状态
+  validate            验证项目配置和知识文件
+  audit               审计模板与机制注册表
+  mcp                 启动 MCP Server（供 IDE 适配器调用）
+  config              配置管理（set / show / check / export / explain / unset）
+  sync                同步模板和适配器（templates / adapters）
+
+完整命令列表: soloforge --list
+版本信息: soloforge version
+`);
+        process.exit(0);
+    }
     switch (command) {
         case "init":
             if (args.includes("--auto")) {
@@ -72,18 +85,6 @@ async function main() {
         case "upgrade-design-artifacts":
             await cmdUpgradeDesignArtifacts();
             break;
-        case "validate-batch1":
-            userWarn("⚠️  validate-batch1 是历史施工命令，不代表正式发布通过。请使用 validate-release。");
-            await cmdValidateFoundation();
-            break;
-        case "validate-batch3":
-            userWarn("⚠️  validate-batch3 是历史施工命令，不代表正式发布通过。请使用 validate-release。");
-            await cmdValidateKnowledge();
-            break;
-        case "validate-batch5":
-            userWarn("⚠️  validate-batch5 是历史施工命令，不代表正式发布通过。请使用 validate-release。");
-            await cmdValidateReleaseGate();
-            break;
         case "validate-release":
             await cmdValidateReleaseGate();
             break;
@@ -108,6 +109,12 @@ async function main() {
         case "validate-new-issue":
             await cmdValidateNewIssue();
             break;
+        case "validate-knowledge":
+            await cmdValidateKnowledge();
+            break;
+        case "validate-foundation":
+            await cmdValidateFoundation();
+            break;
         case "generate-trae":
             await cmdGenerateTrae();
             break;
@@ -122,29 +129,33 @@ async function main() {
         case "config": {
             const subCommand = args[0];
             switch (subCommand) {
-                case "resolve":
-                    await cmdConfigResolve();
+                case "set":
+                    await cmdConfigSet();
+                    break;
+                case "show":
+                    await cmdConfigShow();
+                    break;
+                case "check":
+                    await cmdConfigCheck();
+                    break;
+                case "export":
+                    await cmdConfigExport();
                     break;
                 case "explain":
                     await cmdConfigExplain();
                     break;
-                case "confirm":
-                    await cmdConfigConfirm();
-                    break;
                 case "unset":
                     await cmdConfigUnset();
                     break;
-                case "repair":
-                    await cmdConfigRepair();
-                    break;
                 default:
-                    userInfo("用法: soloforge config <resolve|explain|confirm|unset|repair> [options]");
+                    userInfo("用法: soloforge config <set|show|check|export|explain|unset> [options]");
                     userInfo("");
-                    userInfo("  resolve  解析配置字段优先级（只读，显示所有候选来源）");
-                    userInfo("  explain  解释指定字段的来源和优先级（只读，中文输出）");
-                    userInfo("  confirm  确认配置字段值（写入 config + evidence）");
-                    userInfo("  unset    移除指定字段的确认配置和 evidence");
-                    userInfo("  repair   自动修复机械类型错误并重签 evidence（支持 --dry-run/--json）");
+                    userInfo("  set      写入 intent.yaml 字段（如 set product_profile saas）");
+                    userInfo("  show     显示合并后的完整配置（探测+intent+默认）");
+                    userInfo("  check    运行探测+验证+冲突检测");
+                    userInfo("  export   导出 intent.yaml 原始内容");
+                    userInfo("  explain  解释字段来源和优先级");
+                    userInfo("  unset    移除 intent.yaml 字段");
             }
             break;
         }
@@ -160,6 +171,29 @@ async function main() {
         case "cleanup":
             await cmdCleanup();
             break;
+        case "analyze":
+            await cmdAnalyze();
+            break;
+        case "modify":
+            await cmdModify();
+            break;
+        case "review":
+            await cmdReview();
+            break;
+        case "头脑风暴":
+        case "brainstorm":
+            await cmdBrainstorm();
+            break;
+        case "第一性原理":
+        case "first-principles":
+        case "first_principles":
+            await cmdFirstPrinciples();
+            break;
+        case "推理记录":
+        case "reasoning-log":
+        case "reasoning_log":
+            await cmdReasoningLog();
+            break;
         default:
             userInfo(`SoloForge CLI
 
@@ -179,25 +213,23 @@ async function main() {
   check-bash          PreToolUse hook，阻止 Bash 直接篡改 .soloforge/state 或绕过受控任务写业务实现
   doctor              审计 MCP 控制面、适配器 hook、状态可信和恢复路径
   post-bash           PostToolUse hook，用于跟踪 Bash 执行结果
-  validate            验证项目配置和知识文件（config.yaml 可选，缺失时自动推断）
+  validate            验证项目配置和知识文件（intent.yaml 优先，缺失时自动推断）
   validate-mechanisms 验证双层机制承载模型完整性（模板层 + 机制层）
   audit-template-mechanisms 扫描模板与机制注册表交叉校验（--json 输出完整报告，--changed-only 仅检查变更文件）
   audit-design-artifacts 审计架构/数据库/API 设计产物包（只读，--json 输出报告）
   audit-project-knowledge 审计用户项目 .soloforge/knowledge 自定义规则承载与消费
   upgrade-design-artifacts 生成存量设计资产升级计划（默认 dry-run，--apply --confirm 仅建立已归档迁移基线）
   validate-release    验证发布门禁（契约、场景矩阵、消费 trace、双层机制、回归基线）
-  validate-batch1     [历史] 仅基础契约验证，不代表正式发布通过
-  validate-batch3     [历史] 仅知识模板验证，不代表正式发布通过
-  validate-batch5     [历史] 仅发布门禁验证，不代表正式发布通过
   sync-templates      同步模板到项目（默认 dry-run，--apply 需 --confirm）
   sync-adapters       同步适配器 Prompt（默认 dry-run，--apply 需 --confirm）
   migrate             迁移项目 .soloforge/（默认 dry-run，--apply 需确认）
   version             显示 SoloForge 版本信息
-  config resolve       解析配置字段优先级（只读）
-  config explain        解释配置字段来源（只读，中文）
-  config confirm <field> <value>  确认配置字段（写入 config + evidence）
-  config repair                   自动修复机械类型错误并重签 evidence
-  config unset <field>  移除确认配置
+  config set <field> <value>      写入 intent.yaml 字段
+  config show                     显示合并后的完整配置（探测+intent+默认）
+  config check                    运行探测+验证+冲突检测
+  config export                   导出 intent.yaml 原始内容
+  config explain <field>          解释字段来源和优先级
+  config unset <field>            移除 intent.yaml 字段
   status                显示当前项目的 SoloForge 状态
   next                  查询下一步操作和可执行工作包（默认只读）
   next --json           纯 JSON 输出（无日志污染）
@@ -206,2782 +238,17 @@ async function main() {
   stage --explain       详细解释当前阶段（判断依据、必要条件、下一阶段）
   cleanup               清理过期任务和 evidence（默认 dry-run，--apply 执行实际清理）
   cleanup --stale       检测陈旧 current-task 指针（--apply 时受控归档）
+  analyze               按需调用上下文引擎视图（--view <名称> --targets [...]）
+  modify                脱离管线修改产物（读取 stdin 作为新内容）
+  review                脱离管线审查产物（自动应用 review 规则）
+  头脑风暴 / brainstorm        不确定时决策辅助（列举候选方案 + AI 偏好标注 + 用户选择）
+  第一性原理 / first-principles FP-01~04 规则检查（fundamental_need + 推理链 + 表面修复 + 术语替换）
+  推理记录 / reasoning-log      查看 FP 规则命中和头脑风暴历史记录
 `);
     }
 }
-async function cmdInitAuto() {
-    debug("CLI", "执行 cmdInitAuto");
-    const dryRun = args.includes("--dry-run");
-    const projectPathArg = getArgValue("--project-path");
-    const projectPath = projectPathArg ? path.resolve(projectPathArg) : process.cwd();
-    // 层 1: 确定性指纹探测
-    const fp = await detectFingerprint(projectPath);
-    // 层 2: 规则推导 → config 草案
-    const draft = generateConfigDraft(fp);
-    // 层 3: 字段级 evidence
-    const evidence = generateConfigEvidence(fp, draft, "auto");
-    // 展示探测结果 + evidence
-    userInfo("\nSoloForge 自动配置探测结果:");
-    userInfo("=".repeat(50));
-    for (const [key, field] of Object.entries(evidence.fields)) {
-        const icon = field.confidence === "high" ? "✅" : field.confidence === "medium" ? "⚠️" : "❓";
-        const valStr = typeof field.value === "object" ? JSON.stringify(field.value) : String(field.value);
-        userInfo(`  ${icon} ${key}: ${valStr} (${field.confidence}, ${field.confidence_source})`);
-        userInfo(`     证据: ${field.evidence.join(", ")}`);
-    }
-    userInfo("=".repeat(50));
-    userInfo(`综合置信度: ${draft.confidence}`);
-    if (draft.advisory_notes.length > 0) {
-        userInfo("建议:");
-        for (const note of draft.advisory_notes) {
-            userInfo(`  - ${note}`);
-        }
-    }
-    // Schema 校验 (advisory)
-    const validation = validateConfigDraft(draft);
-    if (validation.warnings.length > 0) {
-        userInfo("\nschema 建议:");
-        for (const w of validation.warnings) {
-            userInfo(`  ⚠️ ${w}`);
-        }
-    }
-    if (!validation.valid) {
-        userInfo("\nschema 错误:");
-        for (const e of validation.errors) {
-            userInfo(`  ❌ ${e}`);
-        }
-        userInfo("\n配置校验失败，请手动运行 `soloforge init --interactive`。");
-        return;
-    }
-    if (dryRun) {
-        userInfo("\n[dry-run] 不写入文件。使用不带 --dry-run 的命令执行写入。");
-        return;
-    }
-    // 写入门禁: 所有必要字段必须 high confidence + detected/user_declared/confirmed
-    const gate = canAutoWrite(evidence);
-    if (!gate.allowed) {
-        userInfo(`\n⚠️ 存在低/中置信度配置项，拒绝写入:`);
-        for (const f of gate.blockedFields) {
-            userInfo(`  - ${f}`);
-        }
-        userInfo("请使用 `soloforge init --interactive` 或 `soloforge init --blueprint \"...\"` 生成配置。");
-        return;
-    }
-    // 写入配置 + evidence
-    await finishInitAutoConfig(projectPath, draft, evidence);
-}
-async function finishInitAutoConfig(projectPath, draft, evidence) {
-    const dirs = [
-        ".soloforge/state", ".soloforge/state/debt",
-        ".soloforge/knowledge/patterns", ".soloforge/knowledge/patterns/core",
-        ".soloforge/knowledge/patterns/temp",
-        ".soloforge/knowledge/procedures", ".soloforge/knowledge/domain/backend",
-        ".soloforge/knowledge/domain/frontend", ".soloforge/knowledge/acceptance_templates",
-        ".soloforge/knowledge/review_rules", ".soloforge/knowledge/product_profiles",
-        ".soloforge/knowledge/checklists", ".soloforge/knowledge/templates",
-        ".soloforge/staged",
-    ];
-    for (const dir of dirs) {
-        fss.mkdirSync(path.join(projectPath, dir), { recursive: true });
-    }
-    writeConfigWithEvidence(projectPath, draft, evidence);
-    ensureGitignore(projectPath);
-    // 继续执行普通 init 的模板复制和适配器生成
-    await copyGlobalPatterns(projectPath);
-    await copyKnowledgeTemplates(projectPath);
-    await generateAdapterConfigs(projectPath, "claude-code");
-}
-function writeConfigWithEvidence(projectPath, draft, evidence) {
-    const configPath = path.join(projectPath, ".soloforge", "config.yaml");
-    const evidencePath = path.join(projectPath, ".soloforge", "config.evidence.json");
-    const yamlConfig = {
-        schema_version: 1,
-        name: draft.name,
-        tech_stack: draft.tech_stack,
-        product_profile: draft.product_profile,
-        repos: [],
-        build_commands: draft.build_commands,
-        scope: draft.scope,
-    };
-    fss.writeFileSync(configPath, YAML.stringify(yamlConfig), "utf-8");
-    // 写入旧版 evidence 格式（向后兼容）+ schema v2 条目
-    fss.writeFileSync(evidencePath, JSON.stringify(evidence, null, 2), "utf-8");
-    // 同时写入 schema v2 条目
-    const v2Entries = Object.entries(evidence.fields).map(([key, field]) => ({
-        field_path: key,
-        value_hash: hashConfigValue(JSON.stringify(field.value)),
-        source: mapLegacySource(field.confidence_source),
-        confidence: field.confidence === "high" ? 1.0 : field.confidence === "medium" ? 0.6 : 0.3,
-        evidence_refs: field.evidence || [],
-        lifetime: "project_persistent",
-        collected_at: evidence.generated_at || new Date().toISOString(),
-    }));
-    // 合并 v2 条目到 evidence 文件
-    try {
-        const existing = JSON.parse(fss.readFileSync(evidencePath, "utf-8"));
-        existing.entries = v2Entries;
-        existing.updated_at = new Date().toISOString();
-        fss.writeFileSync(evidencePath, JSON.stringify(existing, null, 2), "utf-8");
-    }
-    catch (e) {
-        internalWarn("CLI", `更新 evidence 文件失败: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    userInfo(`\n✅ .soloforge/config.yaml + config.evidence.json created`);
-}
-function hashConfigValue(str) {
-    return crypto.createHash("sha256").update(str).digest("hex").slice(0, 16);
-}
-function mapLegacySource(source) {
-    switch (source) {
-        case "detected": return "detected";
-        case "user_declared": return "user_declared";
-        case "confirmed": return "confirmed";
-        default: return "knowledge_default";
-    }
-}
-async function cmdInitBlueprint() {
-    debug("CLI", "执行 cmdInitBlueprint");
-    const blueprintText = getArgValue("--blueprint");
-    if (!blueprintText) {
-        userError("❌ --blueprint 需要提供描述文本，例如: soloforge init --blueprint \"Spring Boot + React 的 B2B 内部管理系统\"");
-        return;
-    }
-    const projectPathArg = getArgValue("--project-path");
-    const projectPath = projectPathArg ? path.resolve(projectPathArg) : process.cwd();
-    const parsed = parseBlueprint(blueprintText);
-    if (!parsed.parsed) {
-        userInfo("⚠️ 无法从蓝图文本解析技术栈，请使用 --interactive。");
-        userInfo("支持的框架关键词: Spring Boot, Go, Rust, Gradle, React, Vue, Angular, Next.js, Nuxt");
-        return;
-    }
-    // 从解析的蓝图构建草稿
-    const draft = {
-        name: path.basename(projectPath),
-        tech_stack: {
-            backend: parsed.tech_stack.backend ?? { lang: "", framework: "", version: "" },
-            frontend: parsed.tech_stack.frontend ?? { lang: "", framework: "", version: "" },
-        },
-        product_profile: parsed.product_profile ?? "default",
-        build_commands: {
-            backend: blueprintBackendCommands(parsed.tech_stack.backend?.framework),
-            frontend: blueprintFrontendCommands(parsed.tech_stack.frontend?.framework),
-        },
-        scope: {
-            backend: parsed.tech_stack.backend ? ["src/"] : [],
-            frontend: parsed.tech_stack.frontend ? ["src/"] : [],
-        },
-        advisory_notes: [],
-        confidence: "high",
-    };
-    const evidence = generateBlueprintEvidence(blueprintText, draft, projectPath);
-    // 创建目录 + 写入配置 + evidence
-    const dirs = [
-        ".soloforge/state", ".soloforge/state/debt",
-        ".soloforge/knowledge/patterns", ".soloforge/knowledge/patterns/core",
-        ".soloforge/knowledge/patterns/temp",
-        ".soloforge/knowledge/procedures", ".soloforge/knowledge/domain/backend",
-        ".soloforge/knowledge/domain/frontend", ".soloforge/knowledge/acceptance_templates",
-        ".soloforge/knowledge/review_rules", ".soloforge/knowledge/product_profiles",
-        ".soloforge/knowledge/checklists", ".soloforge/knowledge/templates",
-        ".soloforge/staged",
-    ];
-    for (const dir of dirs) {
-        fss.mkdirSync(path.join(projectPath, dir), { recursive: true });
-    }
-    writeConfigWithEvidence(projectPath, draft, evidence);
-    ensureGitignore(projectPath);
-    await copyGlobalPatterns(projectPath);
-    await copyKnowledgeTemplates(projectPath);
-    await generateAdapterConfigs(projectPath, "claude-code");
-}
-function blueprintBackendCommands(framework) {
-    switch (framework) {
-        case "spring-boot": return { build: "./mvnw compile -q", test: "./mvnw test -q", full: "./mvnw verify -q" };
-        case "gradle": return { build: "./gradlew compileJava", test: "./gradlew test", full: "./gradlew check" };
-        case "stdlib": return { build: "go build ./...", test: "go test ./...", full: "go test -race ./..." };
-        case "cargo": return { build: "cargo build", test: "cargo test", full: "cargo test --all" };
-        default: return { build: "echo 'no backend build'", test: "echo 'no backend tests'", full: "echo 'no backend'" };
-    }
-}
-function blueprintFrontendCommands(framework) {
-    switch (framework) {
-        case "react":
-        case "vue":
-            return { build: "npm run build", test: "npm test", full: "npm run build && npm test" };
-        case "angular":
-            return { build: "npx ng build", test: "npx ng test", full: "npx ng build && npx ng test" };
-        default: return { build: "echo 'no frontend build'", test: "echo 'no frontend tests'", full: "echo 'no frontend'" };
-    }
-}
-async function cmdInit() {
-    debug("CLI", "执行 cmdInit");
-    const interactive = args.includes("--interactive");
-    const adapter = getArgValue("--adapter") || "claude-code";
-    const projectPathArg = getArgValue("--project-path");
-    const projectPath = projectPathArg ? path.resolve(projectPathArg) : process.cwd();
-    // 创建目录
-    const dirs = [
-        ".soloforge/state",
-        ".soloforge/state/debt",
-        ".soloforge/knowledge/patterns",
-        ".soloforge/knowledge/patterns/core",
-        ".soloforge/knowledge/patterns/temp",
-        ".soloforge/knowledge/procedures",
-        ".soloforge/knowledge/domain/backend",
-        ".soloforge/knowledge/domain/frontend",
-        ".soloforge/knowledge/acceptance_templates",
-        ".soloforge/knowledge/review_rules",
-        ".soloforge/knowledge/product_profiles",
-        ".soloforge/knowledge/checklists",
-        ".soloforge/knowledge/templates",
-        ".soloforge/staged",
-    ];
-    for (const dir of dirs) {
-        fss.mkdirSync(path.join(projectPath, dir), { recursive: true });
-    }
-    // 仅 --interactive 模式生成 config.yaml + evidence；普通 init 不再生成
-    if (interactive) {
-        const config = await interactiveConfig(projectPath);
-        if (config) {
-            // config 结构为 { draft, evidence }
-            writeConfigWithEvidence(projectPath, config.draft, config.evidence);
-        }
-        else if (!process.stdin.isTTY) {
-            userInfo("⚠️ interactive requires TTY. 请使用 --auto 或 --blueprint。");
-        }
-    }
-    // 生成 .mcp.json（SoloForge + Playwright）
-    if (adapter === "claude-code" || adapter === "all") {
-        const mcpPath = path.join(projectPath, ".mcp.json");
-        if (!fss.existsSync(mcpPath)) {
-            const mcpConfig = {
-                mcpServers: {
-                    soloforge: {
-                        command: "soloforge",
-                        args: ["mcp"],
-                        env: { SOLOFORGE_PROJECT: projectPath },
-                    },
-                    playwright: {
-                        command: "npx",
-                        args: ["@playwright/mcp@latest", "--headless"],
-                    },
-                },
-            };
-            fss.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2), "utf-8");
-            userInfo("✅ .mcp.json 已创建（soloforge + playwright）");
-        }
-        // 生成 hooks
-        await cmdGenerateHooks(projectPath);
-        // 生成 CLAUDE.md
-        await cmdGenerateClaudeMdInner(projectPath);
-    }
-    // 生成 Trae IDE 配置
-    if (adapter === "trae" || adapter === "all") {
-        await cmdGenerateTraeInner(projectPath);
-        userInfo("💡 提示: 使用项目级 .trae/ 配置需在 Trae 中开启 beta flag");
-    }
-    // 生成 Codex App 配置
-    if (adapter === "codex" || adapter === "all") {
-        await cmdGenerateCodexInner(projectPath);
-    }
-    // 复制模板 + 适配器配置（共享逻辑）
-    await copyGlobalPatterns(projectPath);
-    await copyKnowledgeTemplates(projectPath);
-    // 确保 .gitignore 包含必要条目
-    ensureGitignore(projectPath);
-    userInfo(`\n✅ SoloForge 初始化完成 (适配器: ${adapter})。${adapter === "trae" ? "请打开 Trae IDE 开始使用。" :
-        adapter === "codex" ? "请打开 Codex App 开始使用。" :
-            adapter === "all" ? "可在 Claude Code、Trae IDE 或 Codex App 中使用。" :
-                "请打开 Claude Code 开始使用。"}`);
-}
-async function copyGlobalPatterns(projectPath) {
-    const { copyPatternsToGlobal } = await import("../engine/template_init_sync.js");
-    const globalDir = getGlobalPatternsDir();
-    const templatesRoot = path.resolve(import.meta.dirname, "..", "..");
-    const result = await copyPatternsToGlobal(templatesRoot, globalDir);
-    const parts = [];
-    if (result.copied > 0)
-        parts.push(`新增 ${result.copied} 个`);
-    if (result.skipped > 0)
-        parts.push(`跳过 ${result.skipped} 个（已存在）`);
-    if (parts.length > 0) {
-        userInfo(`✅ 全局模板 ~/.soloforge/patterns/: ${parts.join("，")}`);
-    }
-}
-async function copyKnowledgeTemplates(projectPath) {
-    const { copyKnowledgeToProject } = await import("../engine/template_init_sync.js");
-    const templatesRoot = path.resolve(import.meta.dirname, "..", "..");
-    const result = await copyKnowledgeToProject(templatesRoot, projectPath);
-    const parts = [];
-    if (result.copied > 0)
-        parts.push(`${result.copied} 个已复制`);
-    if (result.skipped_internal > 0)
-        parts.push(`${result.skipped_internal} 个内部资产已跳过`);
-    if (result.skipped_no_contract > 0)
-        parts.push(`${result.skipped_no_contract} 个无合同已跳过`);
-    if (parts.length > 0) {
-        userInfo(`✅ 知识模板: ${parts.join("，")}`);
-    }
-}
-async function generateAdapterConfigs(projectPath, adapter) {
-    if (adapter === "claude-code" || adapter === "all") {
-        const mcpPath = path.join(projectPath, ".mcp.json");
-        if (!fss.existsSync(mcpPath)) {
-            const mcpConfig = {
-                mcpServers: {
-                    soloforge: { command: "soloforge", args: ["mcp"], env: { SOLOFORGE_PROJECT: projectPath } },
-                    playwright: { command: "npx", args: ["@playwright/mcp@latest", "--headless"] },
-                },
-            };
-            fss.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2), "utf-8");
-            userInfo("✅ .mcp.json 已创建（soloforge + playwright）");
-        }
-        await cmdGenerateHooks(projectPath);
-        await cmdGenerateClaudeMdInner(projectPath);
-    }
-}
-function ensureGitignore(projectPath) {
-    const gitignorePath = path.join(projectPath, ".gitignore");
-    const requiredEntries = [".mcp.json", ".soloforge/"];
-    let content = "";
-    if (fss.existsSync(gitignorePath)) {
-        content = fss.readFileSync(gitignorePath, "utf-8");
-    }
-    const lines = content.split("\n");
-    const missing = requiredEntries.filter((entry) => !lines.some((l) => l.trim() === entry));
-    if (missing.length > 0) {
-        const addition = (content.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n";
-        fss.appendFileSync(gitignorePath, addition, "utf-8");
-        userInfo(`✅ .gitignore 已更新: ${missing.join(", ")}`);
-    }
-}
-async function cmdGenerateHooks(projectPath) {
-    const targetPath = projectPath ?? process.cwd();
-    const hooksConfig = generateHooksConfig();
-    const claudeDir = path.join(targetPath, ".claude");
-    fss.mkdirSync(claudeDir, { recursive: true });
-    const settingsPath = path.join(claudeDir, "settings.json");
-    let existing = {};
-    if (fss.existsSync(settingsPath)) {
-        try {
-            existing = JSON.parse(fss.readFileSync(settingsPath, "utf-8"));
-        }
-        catch {
-            existing = {};
-        }
-    }
-    // 仅 merge hooks 字段，保留用户的 permissions/env 等设置
-    existing.hooks = hooksConfig.hooks;
-    fss.writeFileSync(settingsPath, JSON.stringify(existing, null, 2), "utf-8");
-    userInfo("✅ .claude/settings.json 已更新 hooks 配置");
-}
-async function cmdGenerateClaudeMd() {
-    await cmdGenerateClaudeMdInner(process.cwd());
-}
-async function cmdGenerateTrae() {
-    await cmdGenerateTraeInner(process.cwd());
-}
-async function cmdGenerateCodex() {
-    await cmdGenerateCodexInner(process.cwd());
-}
-async function cmdGenerateCodexInner(projectPath) {
-    // 生成 .codex/config.toml
-    const codexDir = path.join(projectPath, ".codex");
-    fss.mkdirSync(codexDir, { recursive: true });
-    const tomlContent = generateCodexMcpConfig(projectPath);
-    fss.writeFileSync(path.join(codexDir, "config.toml"), tomlContent, "utf-8");
-    userInfo("✅ .codex/config.toml 已创建");
-    // 生成 .codex/hooks.json
-    const hooksContent = generateCodexHooksConfig();
-    fss.writeFileSync(path.join(codexDir, "hooks.json"), hooksContent, "utf-8");
-    userInfo("✅ .codex/hooks.json 已创建");
-    // 生成 AGENTS.md
-    const { config } = await resolveProjectConfig(projectPath);
-    const agentsContent = generateCodexAgentsMd(config);
-    fss.writeFileSync(path.join(projectPath, "AGENTS.md"), agentsContent, "utf-8");
-    userInfo("✅ AGENTS.md 已创建");
-}
-async function cmdGenerateTraeInner(projectPath) {
-    // 生成 .trae/mcp.json
-    const traeDir = path.join(projectPath, ".trae");
-    fss.mkdirSync(traeDir, { recursive: true });
-    const traeMcpPath = path.join(traeDir, "mcp.json");
-    const traeMcpConfig = generateTraeMcpConfig(projectPath);
-    fss.writeFileSync(traeMcpPath, JSON.stringify(traeMcpConfig, null, 2), "utf-8");
-    userInfo("✅ .trae/mcp.json created");
-    // 生成 .trae/rules/project_rules.md
-    const rulesDir = path.join(traeDir, "rules");
-    fss.mkdirSync(rulesDir, { recursive: true });
-    const { config } = await resolveProjectConfig(projectPath);
-    const rulesContent = generateTraeRules(config);
-    fss.writeFileSync(path.join(rulesDir, "project_rules.md"), rulesContent, "utf-8");
-    userInfo("✅ .trae/rules/project_rules.md created");
-}
-async function cmdGenerateClaudeMdInner(projectPath) {
-    const { config } = await resolveProjectConfig(projectPath);
-    const content = generateClaudeMd(config);
-    fss.writeFileSync(path.join(projectPath, "CLAUDE.md"), content, "utf-8");
-    userInfo("✅ CLAUDE.md created");
-}
-async function cmdCheckWrite() {
-    debugLog("CLI: 执行 cmdCheckWrite");
-    try {
-        // 所有适配器均通过 stdin 读取 JSON（Claude Code / Codex 统一）
-        let toolInput;
-        {
-            const chunks = [];
-            for await (const chunk of process.stdin) {
-                chunks.push(chunk);
-            }
-            const stdin = Buffer.concat(chunks).toString().trim();
-            if (stdin)
-                toolInput = stdin;
-        }
-        // 回退: 从命令行参数读取
-        if (!toolInput) {
-            toolInput = args[0];
-        }
-        if (!toolInput) {
-            process.exit(0); // 无输入，放行
-        }
-        const parsed = JSON.parse(toolInput);
-        let filePath;
-        let content;
-        {
-            // Claude Code: { tool_input: { file_path, content/new_string } } 格式
-            // Codex: { input: { file_path, content/new_string } } 格式
-            // 回退: 顶层 { file_path, content/new_string }
-            const input = parsed.tool_input || parsed.input || parsed;
-            filePath = input.file_path || input.path || "";
-            content = input.content || input.new_string || "";
-        }
-        // 加载配置
-        const projectPath = resolveProjectPath();
-        const { config, source } = await resolveProjectConfig(projectPath);
-        // 从配置中收集所有允许路径
-        let allowedPaths = [
-            ...(config.scope.backend || []),
-            ...(config.scope.frontend || []),
-            ...config.repos.flatMap((r) => r.scope || []),
-        ].map((p) => path.resolve(projectPath, p));
-        if (source === "inferred" || allowedPaths.length === 0) {
-            allowedPaths = [...new Set([...allowedPaths, projectPath])];
-        }
-        // 使用 scope_controller 统一检查
-        const { checkScope } = await import("../engine/scope_controller.js");
-        const rawTargetFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(projectPath, filePath);
-        const projectRealPath = fss.realpathSync(projectPath);
-        const targetFilePath = isSameOrDescendantPath(rawTargetFilePath, projectPath, { caseSensitive: false })
-            ? path.join(projectRealPath, path.relative(projectPath, rawTargetFilePath))
-            : rawTargetFilePath;
-        const result = checkScope(targetFilePath, allowedPaths, content || undefined);
-        // 隐私/秘密契约：禁止读取的模式 
-        if (isReadForbidden(filePath)) {
-            process.stdout.write(JSON.stringify({
-                hookSpecificOutput: {
-                    hookEventName: "PreToolUse",
-                    permissionDecision: "deny",
-                    permissionDecisionReason: `隐私策略: ${filePath} 匹配禁止读取模式`,
-                },
-            }));
-            process.exit(0);
-        }
-        if (result.severity === "blocked") {
-            const denyOutput = {
-                hookSpecificOutput: {
-                    hookEventName: "PreToolUse",
-                    permissionDecision: "deny",
-                    permissionDecisionReason: result.reason || "范围检查阻止了写入",
-                },
-            };
-            process.stdout.write(JSON.stringify(denyOutput));
-            process.exit(0);
-        }
-        if (result.severity === "warning") {
-            jsonSafeError(JSON.stringify(result));
-        }
-        const relativeFilePath = path.relative(projectRealPath, targetFilePath).replaceAll(path.sep, "/");
-        const implementationGateReason = await evaluateImplementationWriteGate(projectPath, relativeFilePath);
-        if (implementationGateReason) {
-            denyPreToolUse(implementationGateReason);
-            process.exit(0);
-        }
-        process.exit(0); // 允许
-    }
-    catch (e) {
-        userError(`SoloForge 写入检查错误: ${e instanceof Error ? e.message : String(e)}`);
-        process.exit(1);
-    }
-}
-function resolveProjectPath() {
-    const envPath = process.env.SOLOFORGE_PROJECT;
-    if (envPath) {
-        try {
-            const stat = fss.statSync(envPath);
-            if (!stat.isDirectory()) {
-                userWarn(`⚠️  SOLOFORGE_PROJECT (${envPath}) 不是目录，回退到 cwd`);
-                return process.cwd();
-            }
-            return envPath;
-        }
-        catch {
-            userWarn(`⚠️  SOLOFORGE_PROJECT (${envPath}) 路径不存在，回退到 cwd`);
-            return process.cwd();
-        }
-    }
-    const projectPathArg = getArgValue("--project-path");
-    if (projectPathArg) {
-        return path.resolve(projectPathArg);
-    }
-    return process.cwd();
-}
-function isImplementationSourcePath(relativeFilePath) {
-    if (/^(?:docs|templates|\.soloforge|\.claude|\.codex|\.trae)\//.test(relativeFilePath))
-        return false;
-    if (/(^|\/)(?:package-lock|pnpm-lock|yarn.lock)$/.test(relativeFilePath))
-        return false;
-    return /\.(?:java|kt|kts|scala|ts|tsx|js|jsx|mjs|cjs|py|go|rs|php|rb|cs|swift|vue|svelte|sql|xml|yml|yaml|properties)$/.test(relativeFilePath);
-}
-function isDesignArtifactPath(relativeFilePath) {
-    const lifecyclePaths = getDesignLifecycleArtifactPaths();
-    if ([
-        lifecyclePaths.decision_record,
-        lifecyclePaths.architecture_document,
-        lifecyclePaths.database_document,
-        lifecyclePaths.api_document,
-        lifecyclePaths.optional_detail_design_document,
-        lifecyclePaths.slice_plan,
-        lifecyclePaths.consistency_report,
-        lifecyclePaths.traceability_matrix,
-        lifecyclePaths.openapi,
-    ].includes(relativeFilePath))
-        return true;
-    return /^docs\/architecture\//.test(relativeFilePath) ||
-        /^docs\/traceability\//.test(relativeFilePath) ||
-        /^docs\/api\/openapi\.(?:ya?ml|json)$/.test(relativeFilePath) ||
-        /^db\/(?:migrations?|schema|changelog)\//.test(relativeFilePath) ||
-        /(?:^|\/)(?:src\/main\/resources\/)?db\/(?:migrations?|schema|changelog)\//.test(relativeFilePath);
-}
-function denyPreToolUse(reason) {
-    process.stdout.write(JSON.stringify({
-        hookSpecificOutput: {
-            hookEventName: "PreToolUse",
-            permissionDecision: "deny",
-            permissionDecisionReason: reason,
-        },
-    }));
-}
-async function evaluateImplementationWriteGate(projectPath, relativeFilePath) {
-    // 问题六十二/七十三: Edit/Write/Bash 都必须遵守同一编码前门禁。
-    // 设计资产本身允许继续修订；非设计业务实现文件在产物包复验通过前禁止写入。
-    if (isDesignArtifactPath(relativeFilePath) || !isImplementationSourcePath(relativeFilePath))
-        return undefined;
-    const stateDir = path.join(projectPath, ".soloforge", "state");
-    if (!fss.existsSync(stateDir))
-        return undefined;
-    const { TaskContextManager } = await import("../engine/task_context.js");
-    const manager = new TaskContextManager(stateDir);
-    const currentTask = await manager.getCurrentTask();
-    const designPack = currentTask?.design_artifact_pack;
-    if (currentTask && ["classifying", "clarifying", "expanding"].includes(currentTask.status)) {
-        return `当前 SoloForge 任务仍处于 ${currentTask.status}，说明分类、澄清或意图膨胀未闭合。不得绕过 sf_expand，不得取消/归档当前任务后改用 Bash/Edit/Write 直接写业务实现，也不得把 Bash 作为恢复路径。请先运行 soloforge next 查看阻断项；按返回的 auto_resolvable 或 recovery_command 补齐后重新 sf_expand。只有 soloforge next 明确判定 current-task 陈旧且用户确认时，才可运行 sf_status action=archive_stale confirm=true；归档后仍必须重新 sf_classify → sf_expand 建立受控编码任务。`;
-    }
-    if (!currentTask && hasDesignArtifacts(projectPath)) {
-        return "检测到项目已有架构/详细/API/数据库设计产物，但当前没有受控 SoloForge 任务。不得绕过 sf_classify/sf_expand 直接写业务实现，不得改用 Bash/Edit/Write 先写代码再补验证；请先运行 soloforge next 或通过 MCP 建立编码任务。";
-    }
-    if (currentTask && !designPack && hasDesignArtifacts(projectPath)) {
-        return "检测到项目已有设计产物，但当前任务缺少 design_artifact_pack 复验状态。不得取消任务后直接写业务实现，不得改用 Bash 绕过；请先运行 soloforge audit-design-artifacts，并通过 sf_expand/sf_verify 绑定设计产物包。";
-    }
-    if (designPack && designPack.status !== "implementation_ready") {
-        return `设计产物包状态为 ${designPack.status}，不得改用 Bash/Edit/Write 绕过设计复验；请先完善 docs/architecture、docs/traceability、docs/api/openapi 或 db/migration|migrations|schema|changelog 并通过复验，再写入业务实现`;
-    }
-    return undefined;
-}
-function hasDesignArtifacts(projectPath) {
-    const lifecyclePaths = getDesignLifecycleArtifactPaths();
-    const candidates = [
-        lifecyclePaths.decision_record,
-        lifecyclePaths.architecture_document,
-        lifecyclePaths.database_document,
-        lifecyclePaths.api_document,
-        lifecyclePaths.optional_detail_design_document,
-        lifecyclePaths.slice_plan,
-        lifecyclePaths.consistency_report,
-        lifecyclePaths.traceability_matrix,
-        lifecyclePaths.openapi,
-        path.join(projectPath, "docs", "api", "openapi.yml"),
-        ...lifecyclePaths.sql_roots,
-    ].map((candidate) => path.join(projectPath, candidate));
-    return candidates.some((candidate) => fss.existsSync(candidate));
-}
-async function cmdPostBash() {
-    debugLog("CLI: 执行 cmdPostBash");
-    // Bash 的 PostToolUse hook — 目前为空操作占位符
-    // 未来: 跟踪命令结果，检测构建/测试失败
-    process.exit(0);
-}
-function extractBashCommand(rawInput) {
-    const trimmed = rawInput.trim();
-    if (!trimmed)
-        return "";
-    try {
-        const parsed = JSON.parse(trimmed);
-        const input = parsed.tool_input || parsed.toolInput || parsed.input || parsed;
-        return String(input.command || input.cmd || parsed.command || "");
-    }
-    catch {
-        return trimmed;
-    }
-}
-function unquoteShellToken(token) {
-    if (!token)
-        return undefined;
-    const trimmed = token.trim();
-    if ((trimmed.startsWith("\"") && trimmed.endsWith("\"")) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
-        return trimmed.slice(1, -1);
-    }
-    return trimmed;
-}
-function addShellPathToken(targets, token) {
-    const value = unquoteShellToken(token);
-    if (!value || value === "-" || value.startsWith("$"))
-        return;
-    targets.add(value.replace(/[),;]+$/, ""));
-}
-function addSourcePathTokens(targets, commandText) {
-    const pathTokenPattern = /"([^"]+\.(?:java|kt|kts|scala|ts|tsx|js|jsx|mjs|cjs|py|go|rs|php|rb|cs|swift|vue|svelte|sql|xml|ya?ml|properties))"|'([^']+\.(?:java|kt|kts|scala|ts|tsx|js|jsx|mjs|cjs|py|go|rs|php|rb|cs|swift|vue|svelte|sql|xml|ya?ml|properties))'|([^\s'";&|()<>]+\.(?:java|kt|kts|scala|ts|tsx|js|jsx|mjs|cjs|py|go|rs|php|rb|cs|swift|vue|svelte|sql|xml|ya?ml|properties))/gi;
-    for (const match of commandText.matchAll(pathTokenPattern)) {
-        addShellPathToken(targets, match[1] || match[2] || match[3]);
-    }
-}
-function extractBashWriteTargets(commandText) {
-    const command = commandText.replace(/\s+/g, " ").trim();
-    const targets = new Set();
-    const redirectionPattern = /(?:^|[^<])>>?\s*(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))/g;
-    for (const match of command.matchAll(redirectionPattern)) {
-        addShellPathToken(targets, match[1] || match[2] || match[3]);
-    }
-    const teePattern = /(?:^|[\s;&|()])tee\s+(?:-[A-Za-z]+\s+)*(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))/g;
-    for (const match of command.matchAll(teePattern)) {
-        addShellPathToken(targets, match[1] || match[2] || match[3]);
-    }
-    const writeApiPattern = /(?:writeFileSync|writeFile|write_text)\s*\(\s*["']([^"']+)["']/g;
-    for (const match of command.matchAll(writeApiPattern)) {
-        addShellPathToken(targets, match[1]);
-    }
-    const pythonOpenWritePattern = /open\s*\(\s*["']([^"']+)["']\s*,\s*["'][^"']*[wa+][^"']*["']/g;
-    for (const match of command.matchAll(pythonOpenWritePattern)) {
-        addShellPathToken(targets, match[1]);
-    }
-    const pathlibWritePattern = /(?:Path|pathlib\.Path)\s*\(\s*["']([^"']+)["']\s*\)\.write_text/g;
-    for (const match of command.matchAll(pathlibWritePattern)) {
-        addShellPathToken(targets, match[1]);
-    }
-    const mutatingCommandPattern = /(?:^|[\s;&|()])(?:rm|mv|cp|touch|chmod|chown)\b/i;
-    const inPlaceEditPattern = /(?:^|[\s;&|()])(?:(?:g?sed)\s+[^;&|]*\s-i\b|perl\s+[^;&|]*\s-pi\b)/i;
-    if (mutatingCommandPattern.test(command) || inPlaceEditPattern.test(command)) {
-        addSourcePathTokens(targets, command);
-    }
-    return [...targets];
-}
-function resolveProjectRelativeTarget(projectPath, targetPath) {
-    const rawTargetFilePath = path.isAbsolute(targetPath) ? path.normalize(targetPath) : path.resolve(projectPath, targetPath);
-    const projectRealPath = fss.realpathSync(projectPath);
-    const targetFilePath = isSameOrDescendantPath(rawTargetFilePath, projectPath, { caseSensitive: false })
-        ? path.join(projectRealPath, path.relative(projectPath, rawTargetFilePath))
-        : rawTargetFilePath;
-    const relativeFilePath = path.relative(projectRealPath, targetFilePath).replaceAll(path.sep, "/");
-    if (relativeFilePath === "" || relativeFilePath.startsWith("../") || path.isAbsolute(relativeFilePath))
-        return undefined;
-    return relativeFilePath;
-}
-async function cmdCheckBash() {
-    debugLog("CLI: 执行 cmdCheckBash");
-    try {
-        const chunks = [];
-        for await (const chunk of process.stdin) {
-            chunks.push(chunk);
-        }
-        const stdin = Buffer.concat(chunks).toString();
-        const commandText = extractBashCommand(stdin || args.join(" "));
-        if (isSoloforgeStateBypassCommand(commandText)) {
-            denyPreToolUse("禁止通过 Bash 直接修改 .soloforge/state；请使用 SoloForge MCP 工具，例如 sf_status action=archive_stale confirm=true。");
-            process.exit(0);
-        }
-        const projectPath = resolveProjectPath();
-        for (const target of extractBashWriteTargets(commandText)) {
-            const relativeTarget = resolveProjectRelativeTarget(projectPath, target);
-            if (!relativeTarget)
-                continue;
-            const implementationGateReason = await evaluateImplementationWriteGate(projectPath, relativeTarget);
-            if (implementationGateReason) {
-                denyPreToolUse(`禁止通过 Bash 直接写业务实现文件 ${relativeTarget}；${implementationGateReason}`);
-                process.exit(0);
-            }
-        }
-        process.exit(0);
-    }
-    catch (e) {
-        userError(`SoloForge Bash 检查错误: ${e instanceof Error ? e.message : String(e)}`);
-        process.exit(1);
-    }
-}
-async function cmdDoctor() {
-    debugLog("CLI: 执行 cmdDoctor");
-    const isJson = args.includes("--json");
-    const projectPath = process.cwd();
-    const report = auditControlPlaneProject(projectPath);
-    if (isJson) {
-        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-        return;
-    }
-    userInfo(`SoloForge 控制面诊断: ${projectPath}`);
-    userInfo(`  状态: ${report.passed ? "通过" : "需修复"}`);
-    userInfo(`  控制面矩阵: ${report.matrix_count} 类`);
-    userInfo(`  枝叶细节: ${report.branch_detail_count} 条`);
-    if (report.findings.length === 0) {
-        userInfo("  finding: 0");
-        return;
-    }
-    for (const finding of report.findings) {
-        const marker = finding.severity === "hard_fail" ? "❌" : finding.severity === "warning" ? "⚠️" : "ℹ️";
-        userInfo(`  ${marker} [${finding.code}] ${finding.message}`);
-        userInfo(`     恢复: ${finding.recovery}`);
-    }
-}
-export { buildHookAdditionalContext } from "../adapters/claude_code/pre_prompt_contract.js";
-async function cmdPrePrompt() {
-    debugLog("CLI: 执行 cmdPrePrompt");
-    try {
-        // UserPromptSubmit hook 从 stdin 接收 JSON { prompt: "..." }
-        const chunks = [];
-        for await (const chunk of process.stdin) {
-            chunks.push(chunk);
-        }
-        const stdin = Buffer.concat(chunks).toString().trim();
-        if (!stdin) {
-            process.exit(0);
-            return;
-        }
-        let userMessage = "";
-        try {
-            const parsed = JSON.parse(stdin);
-            userMessage = parsed.prompt || parsed.message || "";
-        }
-        catch {
-            userMessage = stdin;
-        }
-        if (!userMessage || userMessage.length < 2) {
-            process.exit(0);
-            return;
-        }
-        // 使用意图路由器分类 — 如果路由属于 SoloForge 范畴，注入结构化上下文
-        const decision = routeIntent({ intent: userMessage });
-        const additionalContext = buildHookAdditionalContext(decision);
-        if (additionalContext) {
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: typeof additionalContext === "string"
-                        ? additionalContext
-                        : JSON.stringify(additionalContext),
-                },
-            };
-            process.stdout.write(JSON.stringify(output));
-        }
-    }
-    catch (e) {
-        internalWarn("CLI", "pre-prompt hook 错误:", e);
-    }
-    process.exit(0);
-}
-async function checkEvidenceWarnings(projectPath) {
-    debug("CLI", "执行 checkEvidenceWarnings —", projectPath);
-    const warnings = [];
-    const configPath = path.join(projectPath, ".soloforge", "config.yaml");
-    const evidencePath = path.join(projectPath, ".soloforge", "config.evidence.json");
-    if (!fss.existsSync(configPath))
-        return warnings;
-    if (!fss.existsSync(evidencePath)) {
-        warnings.push("config.yaml 存在但 config.evidence.json 缺失 — 来源追溯性丢失");
-        return warnings;
-    }
-    // 检查 mtime 过期
-    try {
-        const configStat = fss.statSync(configPath);
-        const evidenceStat = fss.statSync(evidencePath);
-        if (configStat.mtimeMs > evidenceStat.mtimeMs) {
-            warnings.push("config.evidence.json 已过期（config.yaml 在 evidence 生成后被修改）");
-        }
-    }
-    catch { }
-    // 旧版字段一致性检查（schema v1 evidence）
-    try {
-        const evidenceRaw = JSON.parse(fss.readFileSync(evidencePath, "utf-8"));
-        const configContent = fss.readFileSync(configPath, "utf-8");
-        const config = YAML.parse(configContent);
-        for (const [key, field] of Object.entries(evidenceRaw.fields)) {
-            const actualValue = getConfigFieldValue(config, key);
-            if (actualValue !== undefined && JSON.stringify(field.value) !== JSON.stringify(actualValue)) {
-                warnings.push(`evidence 字段 '${key}' 的值与 config.yaml 不匹配`);
-            }
-        }
-    }
-    catch { }
-    // 使用 schema v2 条目验证配置优先级
-    try {
-        const entries = loadConfigEvidenceEntries(projectPath);
-        // 检查 C 类字段自动写入违规
-        for (const e of entries) {
-            if (e.source === "cli_flag" || e.source === "mcp_param") {
-                if (e.lifetime === "project_persistent") {
-                    warnings.push(`CLI/MCP 参数（${e.source}）已持久化到 config — 字段: ${e.field_path}`);
-                }
-            }
-        }
-        // 运行实时解析的配置优先级验证
-        try {
-            const { reports } = await resolveCurrentProjectConfigReports(projectPath);
-            const findings = validateConfigPrecedence(reports, entries);
-            for (const f of findings) {
-                if (f.severity === "hard_fail") {
-                    warnings.push(`[${f.rule}] ${f.message}`);
-                }
-            }
-        }
-        catch { }
-    }
-    catch { }
-    return warnings;
-}
-function getConfigFieldValue(config, key) {
-    const parts = key.split(".");
-    let obj = config;
-    for (const part of parts) {
-        if (obj == null || typeof obj !== "object")
-            return undefined;
-        obj = obj[part];
-    }
-    return obj;
-}
-async function cmdValidate() {
-    debug("CLI", "执行 cmdValidate");
-    const projectPath = resolveProjectPath();
-    try {
-        const { config, source } = await resolveProjectConfig(projectPath);
-        if (source === "inferred") {
-            userInfo("ℹ️  配置来源: 自动推断");
-        }
-        else {
-            userInfo("✅ config.yaml 有效");
-        }
-        // 使用共享函数验证配置优先级
-        let hasHardFail = false;
-        const hardFailSources = new Set();
-        try {
-            const { reports, entries } = await resolveCurrentProjectConfigReports(projectPath);
-            const findings = validateConfigPrecedence(reports, entries);
-            const hardFails = findings.filter(f => f.severity === "hard_fail");
-            const advisory = findings.filter(f => f.severity === "advisory");
-            if (hardFails.length > 0) {
-                hasHardFail = true;
-                hardFailSources.add("配置优先级");
-                userInfo(`❌ 配置优先级: ${hardFails.length} hard_fail`);
-                for (const f of hardFails) {
-                    userInfo(`  - [${f.rule}] ${f.field_path ?? "N/A"}: ${f.message}`);
-                }
-            }
-            if (advisory.length > 0) {
-                userInfo(`⚠️  配置优先级: ${advisory.length} advisory`);
-                for (const f of advisory) {
-                    userInfo(`  - [${f.rule}] ${f.field_path ?? "N/A"}: ${f.message}`);
-                }
-            }
-            if (hardFails.length === 0 && advisory.length === 0) {
-                userInfo("✅ 配置优先级验证通过");
-            }
-        }
-        catch { }
-        // Evidence 检查
-        const evidenceWarnings = await checkEvidenceWarnings(projectPath);
-        for (const w of evidenceWarnings) {
-            userInfo(`⚠️  evidence: ${w}`);
-        }
-        // 知识治理统一入口：生命周期、语义、文档与语言策略的轻量主链路消费
-        try {
-            const { runKnowledgeGovernanceCheck } = await import("../engine/knowledge_governance_gate.js");
-            const kgReport = runKnowledgeGovernanceCheck({
-                project_language: "zh",
-                contents: [{ id: "cli-validate", domain: "user_feedback", content: "SoloForge 校验输出保持中文语义优先" }],
-            });
-            if (kgReport.hard_fail_count > 0) {
-                userInfo(`❌ 知识治理: ${kgReport.hard_fail_count} hard_fail`);
-                for (const f of kgReport.findings.filter((f) => f.severity === "hard_fail")) {
-                    userInfo(`  - [${f.kind}] ${f.message_zh}`);
-                }
-                hasHardFail = true;
-                hardFailSources.add("知识治理");
-            }
-            else {
-                userInfo(`✅ 知识治理检查: ${kgReport.warning_count} warning, 0 hard_fail`);
-            }
-        }
-        catch (e) {
-            userInfo(`  ⚠ 知识治理检查异常: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        // 检查知识文件
-        const knowledgeDir = getProjectKnowledgeDir(config);
-        if (fss.existsSync(knowledgeDir)) {
-            const { KnowledgeIndexManager } = await import("../knowledge/index_manager.js");
-            const index = new KnowledgeIndexManager(config, { watch: false });
-            try {
-                await index.build();
-                const entries = index.getAllEntries();
-                userInfo(`✅ ${entries.project.length} 条项目知识已索引`);
-                const issues = await index.checkHealth();
-                if (issues.length > 0) {
-                    userInfo(`⚠️  ${issues.length} 个健康问题:`);
-                    for (const { entry, issue } of issues) {
-                        userInfo(`  - ${entry.name}: ${issue}`);
-                    }
-                }
-            }
-            finally {
-                await index.close();
-            }
-            const { auditProjectKnowledge } = await import("../engine/project_knowledge_contract.js");
-            const pkReport = auditProjectKnowledge(projectPath, config);
-            if (pkReport.hard_fail_count > 0) {
-                userInfo(`❌ 项目知识承载: ${pkReport.hard_fail_count} hard_fail`);
-                for (const asset of pkReport.assets) {
-                    for (const finding of asset.findings.filter((f) => f.severity === "hard_fail")) {
-                        userInfo(`  - ${asset.rel_path}: [${finding.code}] ${finding.message_zh}`);
-                    }
-                }
-                hasHardFail = true;
-                hardFailSources.add("项目知识承载");
-            }
-            else {
-                userInfo(`✅ 项目知识承载: ${pkReport.total} 条，${pkReport.injectable} 条可注入，${pkReport.index_only} 条仅索引，0 hard_fail`);
-            }
-        }
-        // 扩展清单校验 (problem-39: validateExtensionManifest)
-        try {
-            const { validateExtensionManifest } = await import("../engine/extension_contract.js");
-            const extResult = validateExtensionManifest({ extension_id: "soloforge-cli-validate", name: "SoloForge CLI 验证", version: "1.0.0", provider: "soloforge", extension_type: "workflow", contract_ids: [], capability_ids: [], permissions: ["read_project"], entrypoints: [], outputs: [], default_state: "disabled", compatibility: { min_soloforge_version: "1.0.0" } }, { extension_id: "soloforge-cli-validate", claimed_capabilities: [], claimed_enforcement: "advisory", third_party: false });
-            if (extResult.violations.length > 0) {
-                userInfo("  ✗ 扩展清单校验失败:");
-                for (const v of extResult.violations)
-                    userInfo(`    - ${v}`);
-                hasHardFail = true;
-                hardFailSources.add("扩展清单");
-            }
-            else {
-                userInfo("  ✓ 扩展清单校验通过");
-            }
-        }
-        catch (e) {
-            userInfo(`  ⚠ 扩展清单校验异常: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        // 平台兼容性检查 (problem-40: normalizePathRef via generatePlatformReport)
-        try {
-            const { generatePlatformReport } = await import("../engine/platform_context.js");
-            const platform = {
-                os: process.platform,
-                arch: process.arch,
-                shell: (process.env.SHELL?.includes("zsh") ? "zsh" : process.env.SHELL?.includes("fish") ? "fish" : "bash"),
-                path_case_sensitive: process.platform !== "darwin" && process.platform !== "win32",
-                path_separator: process.platform === "win32" ? "\\" : "/",
-                line_ending: process.platform === "win32" ? "crlf" : "lf",
-                supports_symlink: process.platform !== "win32",
-                workspace_realpath: projectPath,
-            };
-            const platformReport = generatePlatformReport(platform, ["package.json", "tsconfig.json"], process.cwd());
-            if (platformReport.platform_compatibility_status === "blocked") {
-                userInfo(`  ✗ 平台兼容性阻断: ${platformReport.issues_found.join(", ")}`);
-                hasHardFail = true;
-                hardFailSources.add("平台兼容性");
-            }
-            else {
-                userInfo(`  ✓ 平台兼容性检查: ${platformReport.platform_compatibility_status}`);
-            }
-        }
-        catch (e) {
-            userInfo(`  ⚠ 平台兼容性检查异常: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        // README 命令漂移检测 (problem-30: detectReadmeDrift via validateUserPromise)
-        try {
-            const { validateUserPromise, getCliCommandContracts } = await import("../engine/user_promise.js");
-            const { extractReadmeCommands } = await import("../engine/knowledge_scenario_registry.js");
-            const fs = await import("node:fs");
-            const pathMod = await import("node:path");
-            const readmePath = pathMod.join(projectPath, "README.md");
-            if (fs.existsSync(readmePath)) {
-                const readmeContent = fs.readFileSync(readmePath, "utf-8");
-                const readmeCommands = extractReadmeCommands(readmeContent);
-                const promiseResult = validateUserPromise(readmeCommands, getCliCommandContracts());
-                const hardFails = promiseResult.findings.filter(f => f.severity === "hard_fail");
-                const warnings = promiseResult.findings.filter(f => f.severity === "warning");
-                if (hardFails.length > 0) {
-                    userInfo("  ✗ README 命令漂移:");
-                    for (const hf of hardFails)
-                        userInfo(`    - ${hf.message_zh}`);
-                    hasHardFail = true;
-                    hardFailSources.add("README 命令漂移");
-                }
-                else if (warnings.length > 0) {
-                    userInfo("  ⚠ README 命令漂移警告:");
-                    for (const w of warnings)
-                        userInfo(`    - ${w.message_zh}`);
-                }
-                else {
-                    userInfo("  ✓ README 命令一致性检查通过");
-                }
-            }
-        }
-        catch (e) {
-            userInfo(`  ⚠ README 命令漂移检测异常: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        // 双层机制验证 (仅限 SoloForge 自身源码目录)
-        if (fss.existsSync(path.join(projectPath, "src", "engine", "dual_layer_mechanism_registry.ts"))) {
-            const { validateMechanismLayerMaps } = await import("../engine/dual_layer_mechanism_registry.js");
-            const dlFindings = validateMechanismLayerMaps();
-            const dlHard = dlFindings.filter((f) => f.severity === "hard_fail");
-            const dlAdvisory = dlFindings.filter((f) => f.severity === "advisory");
-            if (dlHard.length > 0) {
-                userInfo(`❌ 双层机制验证: ${dlHard.length} hard_fail`);
-                for (const f of dlHard) {
-                    userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
-                }
-                userError(`❌ validate 失败: 双层机制存在 ${dlHard.length} hard_fail`);
-                process.exit(1);
-            }
-            else {
-                userInfo(`✅ 双层机制验证: ${dlAdvisory.length} advisory, 0 hard_fail`);
-            }
-            // problem-34: 测试策略覆盖验证 — 从 contract_registry 真实元数据构建
-            try {
-                const { validateTestStrategy } = await import("../engine/test_strategy.js");
-                const { getAllContracts } = await import("../engine/contract_registry.js");
-                const enforcedContracts = getAllContracts().filter((c) => c.state === "enforced");
-                let tsHardFail = false;
-                let tsChecked = 0;
-                let tsPending = 0;
-                for (const c of enforcedContracts) {
-                    const hasTests = c.test_files && c.test_files.length > 0;
-                    const hasLifecycle = c.lifecycle_test_files && c.lifecycle_test_files.length > 0;
-                    if (!hasTests) {
-                        // enforced 契约无测试文件元数据 → hard_fail，不得用 required_test_types:[] 掩盖
-                        userInfo(`❌ 测试策略: ${c.contract_id} — enforced 契约缺少 test_files 元数据，无法验证覆盖`);
-                        tsHardFail = true;
-                        tsPending++;
-                        continue;
-                    }
-                    const coverage = {
-                        contract_id: c.contract_id,
-                        required_test_types: ["unit"],
-                        coverage_status: hasLifecycle ? "satisfied" : "partial",
-                        satisfied_types: ["unit"],
-                        missing_types: hasLifecycle ? [] : ["lifecycle"],
-                        test_files: c.test_files || [],
-                        has_lifecycle_test: hasLifecycle,
-                        has_must_fail_case: false,
-                    };
-                    const tsErrors = validateTestStrategy(c.contract_id, true, coverage);
-                    tsChecked++;
-                    for (const e of tsErrors) {
-                        if (e.severity === "hard_fail") {
-                            tsHardFail = true;
-                            userInfo(`❌ 测试策略: ${c.contract_id} — ${e.error}`);
-                        }
-                    }
-                }
-                if (tsHardFail) {
-                    userError(`❌ 测试策略覆盖验证失败: ${tsChecked} 个已检查, ${tsPending} 个元数据缺失`);
-                    hasHardFail = true;
-                    hardFailSources.add("测试策略覆盖");
-                }
-                else {
-                    userInfo(`✅ 测试策略覆盖: 已检查 ${tsChecked} 个 enforced 契约`);
-                }
-            }
-            catch (e) {
-                userError(`❌ 测试策略验证异常: ${e.message}`);
-                hasHardFail = true;
-                hardFailSources.add("测试策略覆盖");
-            }
-        } // 双层机制检查结束
-        try {
-            const { planNextAction } = await import("../engine/next_action_planner.js");
-            const navigation = await planNextAction(projectPath);
-            userInfo(`  阶段: ${navigation.project_stage}${navigation.task_stage ? ` / ${navigation.task_stage}` : ""}`);
-            if (navigation.blocking_reasons.length > 0) {
-                userInfo(`  导航阻断: ${navigation.blocking_reasons.join("; ")}`);
-            }
-            userInfo(`  下一步: ${navigation.work_package?.goal_zh ?? navigation.recommended_prompt_zh}`);
-        }
-        catch (e) {
-            userInfo(`  ⚠ 导航摘要异常: ${e instanceof Error ? e.message : String(e)}`);
-        }
-        if (hasHardFail) {
-            const sources = hardFailSources.size > 0 ? Array.from(hardFailSources).join("、") : "校验项";
-            userError(`❌ validate 失败: ${sources} 存在 hard_fail`);
-            process.exit(1);
-        }
-    }
-    catch (e) {
-        userError(`❌ 验证失败: ${e.message}`);
-        process.exit(1);
-    }
-}
-async function cmdValidateMechanisms() {
-    debug("CLI", "执行 cmdValidateMechanisms");
-    // 从编译后的二进制位置推导根目录: dist/bin/soloforge.js -> 项目根
-    const soloforgeRoot = path.resolve(import.meta.dirname, "..", "..");
-    const projectPath = fss.existsSync(path.join(soloforgeRoot, "src", "engine"))
-        ? soloforgeRoot
-        : process.cwd();
-    try {
-        const { validateMechanismLayerMaps } = await import("../engine/dual_layer_mechanism_registry.js");
-        const findings = validateMechanismLayerMaps(undefined, projectPath);
-        const hardFails = findings.filter((f) => f.severity === "hard_fail");
-        const advisory = findings.filter((f) => f.severity === "advisory");
-        if (findings.length === 0) {
-            userInfo("✅ 所有双层机制映射验证通过，无发现。");
-            process.exit(0);
-            return;
-        }
-        if (advisory.length > 0) {
-            userInfo(`⚠️  advisory findings (${advisory.length}):`);
-            for (const f of advisory) {
-                userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
-            }
-        }
-        if (hardFails.length > 0) {
-            userInfo(`❌ hard_fail findings (${hardFails.length}):`);
-            for (const f of hardFails) {
-                userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
-            }
-            userInfo(`\n❌ 双层机制验证失败: ${hardFails.length} hard_fail`);
-            process.exit(1);
-        }
-        userInfo(`\n✅ 双层机制验证通过，${advisory.length} advisory findings`);
-        // problem-15: 机制族实现一致性验证
-        try {
-            const { validateMechanismFamilies } = await import("../engine/mechanism_family_registry.js");
-            const familyFindings = validateMechanismFamilies();
-            const familyHardFails = familyFindings.filter((f) => f.severity === "hard_fail");
-            if (familyHardFails.length > 0) {
-                userInfo(`\n❌ 机制族验证失败 (${familyHardFails.length} hard_fail):`);
-                for (const f of familyHardFails)
-                    userInfo(`  - ${f.mechanism_id}: ${f.message_zh}`);
-                process.exit(1);
-            }
-            else if (familyFindings.length > 0) {
-                userInfo(`\n📊 机制族验证: ${familyFindings.length} advisory`);
-            }
-        }
-        catch (e) {
-            userError(`❌ 机制族验证异常: ${e.message}`);
-            process.exit(1);
-        }
-        // 审计摘要
-        try {
-            const { auditTemplateMechanisms } = await import("../engine/template_mechanism_auditor.js");
-            const audit = auditTemplateMechanisms(projectPath);
-            if (audit.hard_fail_count > 0) {
-                userInfo(`\n❌ 模板审计摘要: ${audit.hard_fail_count} hard_fail, ${audit.unmapped_template_assets.length} unmapped`);
-                process.exit(1);
-            }
-            else {
-                userInfo(`\n📊 模板审计: ${audit.total_template_files} 文件, ${audit.unmapped_template_assets.length} unmapped, ${audit.advisory_count} advisory`);
-            }
-        }
-        catch (e) {
-            userError(`❌ 模板审计异常: ${e.message}`);
-            process.exit(1);
-        }
-        try {
-            const { runFullHealthCheck } = await import("../engine/mechanism_health_check.js");
-            const health = runFullHealthCheck(projectPath);
-            if (health.hard_fail_count > 0) {
-                userInfo(`\n❌ 机制运行时健康度: ${health.hard_fail_count} hard_fail`);
-                for (const f of health.findings.filter((f) => f.severity === "hard_fail")) {
-                    userInfo(`  - [${f.kind}] ${f.target}: ${f.message_zh}`);
-                }
-                process.exit(1);
-            }
-            userInfo(`\n📊 机制运行时健康度: ${health.warning_count} warning, 0 hard_fail`);
-        }
-        catch (e) {
-            userError(`❌ 机制运行时健康度检查异常: ${e.message}`);
-            process.exit(1);
-        }
-    }
-    catch (e) {
-        userError(`❌ validate-mechanisms 失败: ${e.message}`);
-        process.exit(1);
-    }
-}
-async function cmdAuditTemplateMechanisms() {
-    debug("CLI", "执行 cmdAuditTemplateMechanisms");
-    const asJson = args.includes("--json");
-    const changedOnly = args.includes("--changed-only");
-    // 从编译后的二进制位置推导根目录
-    const soloforgeRoot = path.resolve(import.meta.dirname, "..", "..");
-    const projectPath = fss.existsSync(path.join(soloforgeRoot, "src", "engine"))
-        ? soloforgeRoot
-        : process.cwd();
-    try {
-        const { auditTemplateMechanisms } = await import("../engine/template_mechanism_auditor.js");
-        const report = auditTemplateMechanisms(projectPath);
-        if (asJson) {
-            userInfo(JSON.stringify(report, null, 2));
-            if (report.hard_fail_count > 0) {
-                process.exit(1);
-            }
-            return;
-        }
-        // 人类可读输出
-        userInfo(`模板-机制审计报告 (${report.generated_at})`);
-        userInfo(`  模板文件: ${report.total_template_files}`);
-        userInfo(`  注册资产: ${report.total_registered_assets}`);
-        userInfo(`  机制总数: ${report.total_mechanisms}`);
-        userInfo("");
-        if (report.unmapped_template_assets.length > 0) {
-            userInfo(`⚠️  未注册模板 (${report.unmapped_template_assets.length}):`);
-            for (const u of report.unmapped_template_assets) {
-                userInfo(`  - ${u.path}`);
-            }
-        }
-        if (report.unconsumed_template_assets.length > 0) {
-            userInfo(`⚠️  未消费资产 (${report.unconsumed_template_assets.length}):`);
-            for (const u of report.unconsumed_template_assets) {
-                userInfo(`  - ${u.path} (mode=${u.consumption_mode})`);
-            }
-        }
-        if (report.code_only_mechanisms.length > 0) {
-            userInfo(`⚠️  仅代码机制 (无模板层):`);
-            for (const m of report.code_only_mechanisms) {
-                userInfo(`  - ${m.mechanism_id} (${m.priority}, ${m.status})`);
-            }
-        }
-        if (report.template_only_mechanisms.length > 0) {
-            userInfo(`⚠️  仅模板机制 (无代码层):`);
-            for (const m of report.template_only_mechanisms) {
-                userInfo(`  - ${m.mechanism_id} (${m.priority}, ${m.status})`);
-            }
-        }
-        if (report.required_assets_without_enforcer.length > 0) {
-            userInfo(`❌ Required 资产无 enforcer (${report.required_assets_without_enforcer.length}):`);
-            for (const r of report.required_assets_without_enforcer) {
-                userInfo(`  - ${r.path} (mechanism=${r.owner_mechanism_id})`);
-            }
-        }
-        if (report.overpromised_adapter_rules.length > 0) {
-            userInfo(`❌ 适配器过度承诺 (${report.overpromised_adapter_rules.length}):`);
-            for (const o of report.overpromised_adapter_rules) {
-                userInfo(`  - ${o.source_file}: ${o.promised_mechanism_id} (${o.promise_keywords.join(",")})`);
-            }
-        }
-        if (report.deprecated_assets_injected.length > 0) {
-            userInfo(`⚠️  Deprecated 资产仍被注入:`);
-            for (const d of report.deprecated_assets_injected) {
-                userInfo(`  - ${d.path}`);
-            }
-        }
-        if (report.template_mechanism_drift.length > 0) {
-            const driftHard = report.template_mechanism_drift.filter((f) => f.severity === "hard_fail");
-            const driftAdvisory = report.template_mechanism_drift.filter((f) => f.severity === "advisory");
-            if (driftAdvisory.length > 0) {
-                userInfo(`⚠️  漂移 advisory (${driftAdvisory.length}):`);
-                for (const f of driftAdvisory) {
-                    userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
-                }
-            }
-            if (driftHard.length > 0) {
-                userInfo(`❌ 漂移 hard_fail (${driftHard.length}):`);
-                for (const f of driftHard) {
-                    userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
-                }
-            }
-        }
-        userInfo("");
-        if (report.hard_fail_count > 0) {
-            userInfo(`❌ 审计失败: ${report.hard_fail_count} hard_fail, ${report.advisory_count} advisory`);
-        }
-        else {
-            userInfo(`✅ 审计通过: 0 hard_fail, ${report.advisory_count} advisory`);
-        }
-        // problem-57: 知识资产 schema 审计
-        try {
-            const { auditKnowledgeAssets, parseAssetFile } = await import("../engine/knowledge_asset_audit.js");
-            const knowledgeDirs = [
-                path.join(projectPath, "templates", "knowledge", "procedures"),
-                path.join(projectPath, "templates", "knowledge", "rules"),
-                path.join(projectPath, "templates", "knowledge", "checklists"),
-                path.join(projectPath, "templates", "knowledge", "acceptance_templates"),
-                path.join(projectPath, "templates", "knowledge", "review_rules"),
-                path.join(projectPath, "templates", "knowledge", "workflow_templates"),
-            ];
-            const assets = [];
-            for (const dir of knowledgeDirs) {
-                if (!fss.existsSync(dir))
-                    continue;
-                for (const entry of fss.readdirSync(dir).filter((f) => f.endsWith(".md"))) {
-                    const fp = path.join(dir, entry);
-                    const content = fss.readFileSync(fp, "utf-8");
-                    assets.push(parseAssetFile(fp, content));
-                }
-            }
-            if (assets.length > 0) {
-                const kaReport = auditKnowledgeAssets(assets);
-                userInfo("");
-                userInfo("知识资产审计:");
-                userInfo(`  资产数: ${kaReport.total_assets}`);
-                userInfo(`  通过: ${kaReport.passed ? "✓" : "✗"}`);
-                userInfo(`  hard_fail: ${kaReport.hard_fail_count}, warning: ${kaReport.warning_count}`);
-                for (const f of kaReport.findings) {
-                    const icon = f.severity === "hard_fail" ? "❌" : "⚠️";
-                    userInfo(`    ${icon} ${f.asset_id ?? f.file_path}: ${f.detail} (${f.kind})`);
-                }
-                if (kaReport.hard_fail_count > 0) {
-                    userInfo(`❌ 知识资产审计有 ${kaReport.hard_fail_count} hard_fail`);
-                    process.exit(1);
-                }
-            }
-        }
-        catch (e) {
-            userError(`❌ 知识资产审计异常: ${e.message}`);
-            process.exit(1);
-        }
-        if (report.hard_fail_count > 0) {
-            process.exit(1);
-        }
-    }
-    catch (e) {
-        userError(`❌ audit-template-mechanisms 失败: ${e.message}`);
-        process.exit(1);
-    }
-}
-async function cmdAuditDesignArtifacts() {
-    debug("CLI", "执行 cmdAuditDesignArtifacts");
-    const isJson = args.includes("--json");
-    const projectPath = resolveProjectPath();
-    const { createDesignArtifactPack, verifyDesignArtifactPack } = await import("../engine/design_artifact_pack.js");
-    const contract = createDesignArtifactPack("design-artifact-audit-cli");
-    const result = verifyDesignArtifactPack(projectPath, contract);
-    if (isJson) {
-        userInfo(JSON.stringify({ command: "audit-design-artifacts", project_path: projectPath, ...result }, null, 2));
-    }
-    else {
-        userInfo(`设计产物包审计: ${projectPath}`);
-        userInfo(`  状态: ${result.status}`);
-        userInfo(`  已检查文件: ${result.checked_files.length}`);
-        userInfo(`  hard_fail: ${result.findings.filter((finding) => finding.severity === "hard_fail").length}`);
-        for (const finding of result.findings) {
-            userInfo(`  ${finding.severity === "hard_fail" ? "❌" : "⚠️"} [${finding.code}] ${finding.message_zh}`);
-            if (finding.template_path)
-                userInfo(`     模板: ${finding.template_path}`);
-            if (finding.recovery_command)
-                userInfo(`     命令: ${finding.recovery_command}`);
-            if (finding.recovery_zh)
-                userInfo(`     恢复: ${finding.recovery_zh}`);
-        }
-        if (result.passed)
-            userInfo("✅ 设计产物包复验通过，可作为后续实现输入");
-    }
-    if (!result.passed)
-        process.exit(1);
-}
-/**
- * 存量设计资产升级只负责安全建立复验基线与归档原文。
- * 修正文档内容仍须经 AI 草案和用户确认后写入，再由 audit 命令真实复验。
- */
-async function cmdUpgradeDesignArtifacts() {
-    debug("CLI", "执行 cmdUpgradeDesignArtifacts");
-    const apply = args.includes("--apply");
-    const confirm = args.includes("--confirm");
-    const isJson = args.includes("--json");
-    const projectPath = resolveProjectPath();
-    const { createDesignArtifactPack, verifyDesignArtifactPack } = await import("../engine/design_artifact_pack.js");
-    const contract = createDesignArtifactPack("design-artifact-upgrade-cli");
-    const audit = verifyDesignArtifactPack(projectPath, contract);
-    const presentFiles = audit.checked_files.filter((relativePath) => fss.existsSync(path.join(projectPath, relativePath)));
-    const output = {
-        command: "upgrade-design-artifacts",
-        mode: apply ? "apply" : "dry_run",
-        status: audit.passed ? "implementation_ready" : "needs_revalidation",
-        present_files: presentFiles,
-        findings: audit.findings,
-        next_steps: audit.passed
-            ? ["设计产物已符合当前标准，无需覆盖现有文件"]
-            : ["保留原文归档", "基于 findings 生成修订草案", "用户确认后写入修订文档/OpenAPI/SQL", "重新执行 audit-design-artifacts"],
-    };
-    if (!apply) {
-        if (isJson)
-            userInfo(JSON.stringify(output, null, 2));
-        else {
-            userInfo("设计产物升级计划: dry-run（不会修改现有文档）");
-            userInfo(`  当前状态: ${output.status}`);
-            userInfo(`  已发现现有资产: ${presentFiles.length}`);
-            userInfo(`  待修复项: ${audit.findings.length}`);
-            userInfo("  使用 --apply --confirm 仅归档现有基线并登记 needs_revalidation；修订内容仍须用户确认。");
-        }
-        return;
-    }
-    if (!confirm) {
-        userError("❌ upgrade-design-artifacts --apply 必须同时提供 --confirm，禁止静默改写或归档现有设计文档");
-        process.exit(1);
-    }
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const archiveDir = path.join(projectPath, ".soloforge", "design-artifacts", "archive", timestamp);
-    fss.mkdirSync(archiveDir, { recursive: true });
-    for (const relativePath of presentFiles) {
-        const target = path.join(archiveDir, relativePath);
-        fss.mkdirSync(path.dirname(target), { recursive: true });
-        fss.copyFileSync(path.join(projectPath, relativePath), target);
-    }
-    const contractDir = path.join(projectPath, ".soloforge", "design-artifacts");
-    fss.mkdirSync(contractDir, { recursive: true });
-    fss.writeFileSync(path.join(contractDir, "upgrade-contract.json"), JSON.stringify({
-        ...contract,
-        status: audit.passed ? "implementation_ready" : "needs_revalidation",
-        baseline_hashes: audit.hashes,
-        findings: audit.findings,
-        verified_at: new Date().toISOString(),
-        archive_dir: path.relative(projectPath, archiveDir),
-        write_policy: "原文仅归档；修订文档须由用户确认后另行写入并重新复验",
-    }, null, 2), "utf-8");
-    const appliedOutput = { ...output, archive_dir: path.relative(projectPath, archiveDir), original_documents_overwritten: false };
-    if (isJson)
-        userInfo(JSON.stringify(appliedOutput, null, 2));
-    else {
-        userInfo(`✅ 已归档现有设计基线: ${appliedOutput.archive_dir}`);
-        userInfo("  未覆盖现有设计文档；请确认修订草案后重新执行复验。");
-    }
-}
-async function cmdValidateKnowledge() {
-    debug("CLI", "执行 cmdValidateKnowledge");
-    const { validateContractRegistry } = await import("../engine/contract_registry.js");
-    const { listProblemsByBatch } = await import("../engine/implementation_roadmap_registry.js");
-    const { runAllKnowledgeScenarios, extractReadmeCommands } = await import("../engine/knowledge_scenario_registry.js");
-    const { listKnowledgeIssueDetailAcceptances, validateKnowledgeIssueDetailAcceptance, } = await import("../engine/knowledge_acceptance_registry.js");
-    const isJson = args.includes("--json");
-    const cwd = process.cwd();
-    const fs = await import("node:fs");
-    const pathModule = await import("node:path");
-    // 收集项目文件集合
-    const existingFiles = new Set();
-    function walkDir(dir, prefix) {
-        try {
-            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-                const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
-                if (entry.isDirectory()) {
-                    walkDir(pathModule.join(dir, entry.name), rel);
-                }
-                else {
-                    existingFiles.add(rel);
-                }
-            }
-        }
-        catch { /* 忽略不存在目录 */ }
-    }
-    walkDir(pathModule.join(cwd, "src"), "src");
-    walkDir(pathModule.join(cwd, "tests"), "tests");
-    // 验证契约注册表
-    const contractFindings = validateContractRegistry(existingFiles);
-    const hardFails = contractFindings.filter((f) => f.severity === "hard_fail");
-    // 验证 知识模板问题状态
-    const knowledgeProblems = listProblemsByBatch("batch-3");
-    const allImplemented = knowledgeProblems.every((p) => p.status === "implemented_verified");
-    // 读取真实 README 并提取命令
-    let readmeCommands;
-    try {
-        const readmeContent = fs.readFileSync(pathModule.join(cwd, "README.md"), "utf-8");
-        readmeCommands = extractReadmeCommands(readmeContent);
-    }
-    catch { /* README 不存在时跳过 */ }
-    // 运行真实场景矩阵
-    const scenarioResults = runAllKnowledgeScenarios(readmeCommands);
-    const scenariosPass = scenarioResults.every((s) => s.status === "PASS");
-    // 验证 IssueDetailAcceptance 注册表
-    const acceptances = listKnowledgeIssueDetailAcceptances();
-    const acceptanceFindings = acceptances.flatMap((a) => validateKnowledgeIssueDetailAcceptance(a));
-    const acceptanceHardFails = acceptanceFindings.filter((f) => f.severity === "hard_fail");
-    const result = {
-        knowledge_problems: knowledgeProblems.length,
-        all_implemented_verified: allImplemented,
-        contract_hard_fails: hardFails.length,
-        issue_acceptances: acceptances.length,
-        acceptance_hard_fails: acceptanceHardFails.length,
-        scenarios_pass: scenariosPass,
-        scenario_results: scenarioResults.map((s) => ({
-            scenario_id: s.scenario_id,
-            scenario_name: s.scenario_name,
-            status: s.status,
-            evidence: s.evidence,
-            failures: s.failures.length,
-        })),
-    };
-    if (isJson) {
-        userInfo(JSON.stringify(result, null, 2));
-    }
-    else {
-        userInfo("═══ Batch 3 验证 ═══");
-        userInfo(`  问题数: ${knowledgeProblems.length}`);
-        userInfo(`  全部 implemented_verified: ${allImplemented ? "✓" : "✗"}`);
-        userInfo(`  契约 hard_fail: ${hardFails.length}`);
-        for (const f of hardFails) {
-            userInfo(`    ✗ ${f.contract_id}: ${f.message_zh}`);
-        }
-        userInfo(`  IssueDetailAcceptance: ${acceptances.length} 条, hard_fail: ${acceptanceHardFails.length}`);
-        for (const f of acceptanceHardFails) {
-            userInfo(`    ✗ ${f.issue_id}: ${f.message_zh}`);
-        }
-        userInfo(`  场景矩阵:`);
-        for (const s of scenarioResults) {
-            const icon = s.status === "PASS" ? "✓" : "✗";
-            userInfo(`    ${icon} ${s.scenario_id}: ${s.scenario_name} — ${s.status}`);
-            for (const ev of s.evidence) {
-                userInfo(`      ✓ ${ev}`);
-            }
-            for (const fl of s.failures) {
-                userInfo(`      ✗ ${fl}`);
-            }
-        }
-        const overallPass = allImplemented && hardFails.length === 0 && scenariosPass && acceptanceHardFails.length === 0;
-        userInfo(overallPass ? "\n✅ Batch 3 验证通过" : "\n❌ Batch 3 验证失败");
-    }
-    const overallPass = allImplemented && hardFails.length === 0 && scenariosPass && acceptanceHardFails.length === 0;
-    process.exit(overallPass ? 0 : 1);
-}
-async function cmdSyncTemplates() {
-    debug("CLI", "执行 cmdSyncTemplates");
-    const apply = args.includes("--apply");
-    const confirm = args.includes("--confirm");
-    const isJson = args.includes("--json");
-    const { executeSync, validateSyncSafety, computeTemplateAssetVersions } = await import("../engine/template_sync.js");
-    const { validateWorkflowTemplatePack, createWorkflowTemplatePackContract, createWorkflowTemplateEntry, createTemplateConsumptionEvidence, } = await import("../engine/workflow_template_pack.js");
-    const { buildTemplateManifestFromSource, computeFileHashes, loadProjectManifest, saveProjectManifest, writeFileSyncRecursive, sha256Hex, hashFile, } = await import("../engine/template_manifest_io.js");
-    const projectPath = process.cwd();
-    const packageRoot = path.resolve(import.meta.dirname, "..", "..");
-    const sourceDir = args.find((a) => a.startsWith("--source="))?.slice("--source=".length) ?? path.join(packageRoot, "templates");
-    if (apply) {
-        const { classifyConfigContext, validateWriteBoundary } = await import("../engine/config_write_boundary.js");
-        const writeContext = classifyConfigContext(projectPath, { confirmed: confirm });
-        const violations = validateWriteBoundary(writeContext, [
-            path.join(projectPath, ".soloforge", "template-manifest.json"),
-            path.join(projectPath, ".soloforge", "knowledge"),
-        ]);
-        if (violations.length > 0) {
-            for (const v of violations)
-                userError(`❌ 模板同步写入边界阻断: ${v.target_path} — ${v.reason_zh}`);
-            process.exit(1);
-        }
-    }
-    // 读取当前包版本
-    let packageVersion = "0.0.0";
-    try {
-        const pkgJson = JSON.parse(fss.readFileSync(path.join(packageRoot, "package.json"), "utf-8"));
-        packageVersion = pkgJson.version;
-    }
-    catch { /* 回退 */ }
-    // 构建源清单（真实模板文件）
-    const sourceManifest = buildTemplateManifestFromSource(sourceDir, packageVersion);
-    // 加载已安装清单
-    const installedManifest = loadProjectManifest(projectPath) ?? [];
-    // 计算哈希（Map key 用相对路径，与 computeTemplateAssetVersions 查找键一致）
-    const sourceHashes = new Map();
-    for (const e of sourceManifest) {
-        const h = hashFile(path.join(packageRoot, e.source_path));
-        if (h !== null)
-            sourceHashes.set(e.source_path, h);
-    }
-    const baseManifest = installedManifest.length > 0 ? installedManifest : sourceManifest;
-    const currentHashes = new Map();
-    for (const e of baseManifest) {
-        const h = hashFile(path.join(projectPath, e.target_path));
-        if (h !== null)
-            currentHashes.set(e.target_path, h);
-    }
-    // 计算差异（首次安装用 sourceManifest 作为基准，全部为 missing）
-    const assets = computeTemplateAssetVersions(baseManifest, currentHashes, sourceHashes);
-    // problem-53: 工作流模板包完整性校验 — 用真实 manifest 数据构建 pack
-    const wfPackEntries = sourceManifest
-        .filter(e => e.asset_kind === "workflow_template")
-        .map(e => createWorkflowTemplateEntry("architecture_design", e.target_path));
-    const wfConsumptionEvidences = assets
-        .filter(a => wfPackEntries.some(w => w.template_path === a.target_path))
-        .map(a => createTemplateConsumptionEvidence(a.target_path));
-    if (wfPackEntries.length > 0) {
-        const wfPack = createWorkflowTemplatePackContract({
-            workflows: wfPackEntries,
-            mechanism_consumption_map: sourceManifest
-                .filter(e => e.asset_kind === "workflow_template")
-                .map(e => ({ template_path: e.target_path, consumed_mechanism_id: `mc-${e.asset_id}`, consumption_type: "route_trigger", evidence_required: true })),
-        });
-        const wfResult = validateWorkflowTemplatePack(wfPack, wfConsumptionEvidences);
-        if (!wfResult.valid && !isJson) {
-            userInfo(`  ⚠ 工作流模板包校验: ${wfResult.violations.length} 个违规`);
-            for (const v of wfResult.violations)
-                userInfo(`    - ${v}`);
-        }
-        if (!wfResult.valid && apply) {
-            // 校验失败阻断 apply
-            internalWarn("CLI", `工作流模板包校验失败，apply 已阻断。违规: ${wfResult.violations.join("; ")}`);
-            process.exit(1);
-        }
-    }
-    const safeCheck = validateSyncSafety(assets);
-    try {
-        const { runKnowledgeGovernanceCheck } = await import("../engine/knowledge_governance_gate.js");
-        const kgReport = runKnowledgeGovernanceCheck({
-            project_language: "zh",
-            contents: sourceManifest.slice(0, 12).map((e) => ({ id: e.asset_id, domain: "governance_contracts", content: e.target_path })),
-        });
-        if (kgReport.hard_fail_count > 0 && apply) {
-            userError(`❌ 知识治理阻断模板同步: ${kgReport.hard_fail_count} hard_fail`);
-            process.exit(1);
-        }
-    }
-    catch (e) {
-        if (!isJson)
-            userInfo(`  ⚠ 知识治理同步检查异常: ${e instanceof Error ? e.message : String(e)}`);
-    }
-    const syncResult = executeSync({ dry_run: !apply, apply, confirm, project_path: projectPath, source_path: sourceDir }, assets, sourceManifest);
-    // apply 模式：真实文件复制
-    if (apply && confirm && syncResult.success && syncResult.backup_path) {
-        const backupDir = syncResult.backup_path;
-        fss.mkdirSync(backupDir, { recursive: true });
-        const assetMap = new Map(assets.map((a) => [a.asset_id, a]));
-        const updatedManifest = [...sourceManifest];
-        for (const assetId of [...syncResult.report.added, ...syncResult.report.updated]) {
-            const asset = assetMap.get(assetId);
-            if (!asset)
-                continue;
-            const srcAbs = path.join(packageRoot, asset.source_path);
-            const tgtAbs = path.join(projectPath, asset.target_path);
-            // 备份已有文件
-            if (fss.existsSync(tgtAbs)) {
-                const backupFile = path.join(backupDir, path.basename(tgtAbs));
-                fss.copyFileSync(tgtAbs, backupFile);
-            }
-            // 复制源文件到目标
-            writeFileSyncRecursive(tgtAbs, fss.readFileSync(srcAbs));
-            // 更新清单中的 installed_hash
-            const idx = updatedManifest.findIndex((e) => e.asset_id === assetId);
-            if (idx >= 0) {
-                updatedManifest[idx] = {
-                    ...updatedManifest[idx],
-                    installed_hash: asset.source_hash,
-                    installed_at: new Date().toISOString(),
-                };
-            }
-        }
-        // 持久化清单
-        saveProjectManifest(projectPath, updatedManifest);
-    }
-    if (isJson) {
-        userInfo(JSON.stringify({
-            command: "sync-templates",
-            mode: apply ? "apply" : "dry_run",
-            total_assets: assets.length,
-            safe: safeCheck.safe,
-            result: syncResult.success,
-            dry_run: syncResult.dry_run,
-            report: syncResult.report,
-        }, null, 2));
-    }
-    else {
-        userInfo(apply ? "模板同步: apply 模式" : "模板同步: dry-run 模式（不写入文件）");
-        userInfo(`  资产总数: ${assets.length}`);
-        userInfo(`  应用安全: ${safeCheck.safe ? "安全" : "需确认"}`);
-        userInfo(`  结果: ${syncResult.success ? "成功" : "失败"}`);
-        userInfo(`  新增: ${syncResult.report.added.length}`);
-        userInfo(`  更新: ${syncResult.report.updated.length}`);
-        userInfo(`  跳过(用户修改): ${syncResult.report.skipped_user_modified.length}`);
-        userInfo(`  废弃: ${syncResult.report.deprecated.length}`);
-        if (!apply)
-            userInfo("  使用 --apply --confirm 应用同步；需确认表示 dry-run 发现现有用户资产，不会自动覆盖");
-    }
-    if (!syncResult.success)
-        process.exit(1);
-}
-async function cmdSyncAdapters() {
-    debug("CLI", "执行 cmdSyncAdapters");
-    const apply = args.includes("--apply");
-    const confirm = args.includes("--confirm");
-    const isJson = args.includes("--json");
-    const { syncAdapterPrompts, validateAdapterPrompt, REQUIRED_ADAPTER_SECTIONS, } = await import("../engine/adapter_prompt_contract.js");
-    const { writeFileSyncRecursive, sha256Hex, hashFile, } = await import("../engine/template_manifest_io.js");
-    const projectPath = process.cwd();
-    // 加载项目配置（回退到默认）
-    let config;
-    try {
-        const resolved = await resolveProjectConfig(projectPath);
-        config = resolved.config;
-    }
-    catch {
-        config = {
-            name: "default", tech_stack: { backend: { lang: "", framework: "", version: "" }, frontend: { lang: "", framework: "", version: "" } },
-            product_profile: "general", repos: [], build_commands: { backend: {}, frontend: {} }, scope: { backend: [], frontend: [] },
-        };
-    }
-    // 适配器生成器
-    const { generateClaudeMd } = await import("../adapters/claude_code/claude_md.js");
-    const { generateCodexAgentsMd } = await import("../adapters/codex/codex_rules.js");
-    const { generateTraeRules } = await import("../adapters/trae/trae_rules.js");
-    const sections = [...REQUIRED_ADAPTER_SECTIONS];
-    // 适配器 installed hash 记录文件
-    const ADAPTER_HASH_FILE = ".soloforge/adapter_hashes.json";
-    // 加载已安装的适配器 hash 记录
-    let installedAdapterHashes = {};
-    try {
-        const hashContent = fss.readFileSync(path.join(projectPath, ADAPTER_HASH_FILE), "utf-8");
-        installedAdapterHashes = JSON.parse(hashContent);
-    }
-    catch { /* 首次无记录 */ }
-    const adapterContracts = [
-        {
-            adapter_id: "claude-code", host_type: "claude_code",
-            prompt_path: "CLAUDE.md",
-            generated_from_contract_version: "1",
-            required_sections: sections,
-            forbidden_claims: [],
-            sync_required: true,
-            next_allowed_tools: ["sf_classify", "sf_expand", "sf_verify", "sf_learn", "sf_deliver", "sf_review"],
-        },
-        {
-            adapter_id: "codex", host_type: "codex",
-            prompt_path: "AGENTS.md",
-            generated_from_contract_version: "1",
-            required_sections: sections,
-            forbidden_claims: [],
-            sync_required: true,
-            next_allowed_tools: ["sf_classify", "sf_expand", "sf_verify", "sf_learn"],
-        },
-        {
-            adapter_id: "trae", host_type: "cursor",
-            prompt_path: ".trae/rules/project_rules.md",
-            generated_from_contract_version: "1",
-            required_sections: sections,
-            forbidden_claims: [],
-            sync_required: true,
-            next_allowed_tools: ["sf_classify", "sf_expand", "sf_verify", "sf_learn"],
-        },
-    ];
-    // 验证所有适配器
-    const validations = syncAdapterPrompts(adapterContracts, { dry_run: !apply, apply, confirm });
-    // 适配器内容生成
-    const generators = {
-        "claude-code": () => generateClaudeMd(config),
-        "codex": () => generateCodexAgentsMd(config),
-        "trae": () => generateTraeRules(config),
-    };
-    // apply 模式：写入合规的适配器文件
-    const writtenFiles = [];
-    const skippedFiles = [];
-    if (apply && confirm) {
-        const updatedHashes = { ...installedAdapterHashes };
-        for (const contract of adapterContracts) {
-            const validation = validations.find((v) => v.adapter_id === contract.adapter_id);
-            if (!validation?.compliant) {
-                skippedFiles.push(`${contract.adapter_id}: 不合规，跳过`);
-                continue;
-            }
-            const targetPath = path.join(projectPath, contract.prompt_path);
-            const generator = generators[contract.adapter_id];
-            if (!generator)
-                continue;
-            const content = generator();
-            const generatedHash = sha256Hex(content);
-            // 用户修改检测：文件存在且 hash 与已安装 hash 不一致
-            if (fss.existsSync(targetPath)) {
-                const diskHash = hashFile(targetPath);
-                const installedHash = installedAdapterHashes[contract.adapter_id];
-                if (diskHash && installedHash && diskHash !== installedHash) {
-                    // 文件被用户修改，不得覆盖
-                    skippedFiles.push(`${contract.adapter_id}: 用户已修改，跳过`);
-                    continue;
-                }
-            }
-            // 首次安装或内容有变化：写入
-            writeFileSyncRecursive(targetPath, content);
-            writtenFiles.push(contract.prompt_path);
-            updatedHashes[contract.adapter_id] = generatedHash;
-        }
-        // 持久化 hash 记录
-        writeFileSyncRecursive(path.join(projectPath, ADAPTER_HASH_FILE), JSON.stringify(updatedHashes, null, 2));
-    }
-    if (isJson) {
-        userInfo(JSON.stringify({
-            command: "sync-adapters",
-            mode: apply ? "apply" : "dry_run",
-            adapter_count: adapterContracts.length,
-            validations,
-            written: writtenFiles,
-            skipped: skippedFiles,
-        }, null, 2));
-    }
-    else {
-        userInfo(apply ? "适配器同步: apply 模式" : "适配器同步: dry-run 模式（不写入文件）");
-        userInfo(`  适配器数量: ${adapterContracts.length}`);
-        for (const v of validations) {
-            const icon = v.compliant ? "✓" : "✗";
-            userInfo(`  ${icon} ${v.adapter_id}: ${v.compliant ? "合规" : "不合规"}`);
-            for (const f of v.findings) {
-                if (f.severity !== "info")
-                    userInfo(`    ${f.severity === "critical" ? "✗" : "⚠"} ${f.message_zh}`);
-            }
-        }
-        if (writtenFiles.length > 0) {
-            userInfo(`  已写入: ${writtenFiles.join(", ")}`);
-        }
-        if (skippedFiles.length > 0) {
-            userInfo(`  已跳过: ${skippedFiles.join("; ")}`);
-        }
-        if (!apply)
-            userInfo("  使用 --apply --confirm 应用同步");
-    }
-}
-async function cmdMigrate() {
-    debug("CLI", "执行 cmdMigrate");
-    const apply = args.includes("--apply");
-    const confirm = args.includes("--confirm");
-    const isJson = args.includes("--json");
-    const { createMigrationPlan, getCurrentCompatibility, validateMigrationSafety, generateVersionFile } = await import("../engine/release_compatibility.js");
-    const { loadProjectVersion, saveProjectVersion, writeFileSyncRecursive } = await import("../engine/template_manifest_io.js");
-    const projectPath = process.cwd();
-    const compat = getCurrentCompatibility();
-    const toVersion = compat.package_version;
-    // 读取项目已安装版本，不存在视为首次
-    const installed = loadProjectVersion(projectPath);
-    const fromVersion = installed?.soloforge_package_version ?? "0.0.0";
-    // 版本相同，无需迁移
-    if (fromVersion === toVersion) {
-        if (isJson) {
-            userInfo(JSON.stringify({
-                command: "migrate",
-                mode: "noop",
-                success: true,
-                dry_run: !apply,
-                safe: true,
-                message: `已是最新版本 ${toVersion}`,
-                from_version: fromVersion,
-                to_version: toVersion,
-            }, null, 2));
-        }
-        else {
-            userInfo(`项目迁移: 已是最新版本 ${toVersion}`);
-            userInfo(`  当前版本: ${fromVersion}`);
-        }
-        return;
-    }
-    // 先生成真实迁移计划
-    const plan = createMigrationPlan({ dry_run: !apply, apply, confirm, project_path: projectPath, from_version: fromVersion, to_version: toVersion }, compat);
-    // 基于真实 plan 做安全检查
-    const safetyCheck = validateMigrationSafety(plan.plan, apply, !!confirm);
-    // apply --confirm 模式且安全通过时：创建备份 + 写入 version.json
-    if (apply && confirm && plan.success && safetyCheck.safe && plan.backup_path) {
-        const backupDir = path.join(projectPath, plan.backup_path);
-        fss.mkdirSync(backupDir, { recursive: true });
-        // 备份已有 version.json
-        const versionPath = path.join(projectPath, ".soloforge/version.json");
-        if (fss.existsSync(versionPath)) {
-            fss.copyFileSync(versionPath, path.join(backupDir, "version.json"));
-        }
-        // 写入新版本文件
-        const versionContent = generateVersionFile(toVersion, compat.contract_registry_version);
-        // 合并 created_at（首次用新时间，升级保留原时间）
-        if (installed?.created_at) {
-            versionContent.created_at = installed.created_at;
-        }
-        saveProjectVersion(projectPath, versionContent);
-    }
-    const success = plan.success && safetyCheck.safe;
-    if (isJson) {
-        userInfo(JSON.stringify({
-            command: "migrate",
-            mode: apply ? "apply" : "dry_run",
-            success,
-            dry_run: plan.dry_run,
-            safe: safetyCheck.safe,
-            from_version: fromVersion,
-            to_version: toVersion,
-            plan: plan.plan,
-            backup_path: plan.backup_path,
-        }, null, 2));
-    }
-    else {
-        userInfo(apply ? "项目迁移: apply 模式" : "项目迁移: dry-run 模式（不写入文件）");
-        userInfo(`  结果: ${success ? "成功" : "失败"}`);
-        userInfo(`  从版本: ${fromVersion}`);
-        userInfo(`  到版本: ${toVersion}`);
-        userInfo(`  安全检查: ${safetyCheck.safe ? "✓" : "✗"}`);
-        userInfo(`  需迁移: ${plan.plan.required_migrations.length}`);
-        userInfo(`  自动应用: ${plan.plan.auto_applicable.length}`);
-        userInfo(`  需人工: ${plan.plan.requires_human.length}`);
-        if (!apply)
-            userInfo("  使用 --apply --confirm 执行迁移");
-    }
-    if (!success)
-        process.exit(1);
-}
-async function cmdValidateReleaseGate() {
-    const isJson = args.includes("--json");
-    debug("CLI", "执行 cmdValidateReleaseGate");
-    const { runReleaseReadinessGate } = await import("../engine/release_readiness_gate.js");
-    const result = await runReleaseReadinessGate(process.cwd());
-    if (isJson) {
-        userInfo(JSON.stringify({
-            passed: result.passed,
-            hard_fail_count: result.hard_fail_count,
-            hard_fails: result.hard_fails,
-            phases: result.phases,
-        }, null, 2));
-    }
-    else {
-        userInfo("══════════════════════════════════════════════════════════════");
-        userInfo(`发布结论: ${result.passed ? "PASS" : "FAIL"}`);
-        userInfo(`hard_fail 数量: ${result.hard_fail_count}`);
-        userInfo("══════════════════════════════════════════════════════════════");
-        userInfo();
-        for (const p of result.phases) {
-            userInfo(`  ${p.hard_fail_count === 0 ? "[PASS]" : "[FAIL]"} ${p.name} — ${p.hard_fail_count} hard_fail`);
-        }
-        if (result.hard_fails.length > 0) {
-            userInfo();
-            userInfo("━━━ hard_fail 明细 ━━━");
-            for (let i = 0; i < result.hard_fails.length; i++) {
-                const hf = result.hard_fails[i];
-                userInfo(`[${i + 1}] ${hf.code}: ${hf.message}`);
-                userInfo(`    涉及: ${hf.files.join(", ")}`);
-                userInfo(`    下一步: ${hf.nextStep}`);
-            }
-        }
-    }
-    if (!result.passed)
-        process.exit(1);
-}
-async function cmdValidateFoundation() {
-    debug("CLI", "执行 cmdValidateFoundation");
-    const { validateMechanismLayerMaps, listMechanismLayerMaps } = await import("../engine/dual_layer_mechanism_registry.js");
-    const { auditTemplateMechanisms } = await import("../engine/template_mechanism_auditor.js");
-    const { validateFoundationScenarios, validateFoundationProblemMatrix } = await import("../engine/foundation_scenario_registry.js");
-    const cwd = process.cwd();
-    const maps = listMechanismLayerMaps();
-    const mechFindings = validateMechanismLayerMaps(maps, cwd);
-    const mechanismsPass = mechFindings.filter((f) => f.severity === "hard_fail").length === 0;
-    const auditReport = auditTemplateMechanisms(cwd);
-    const auditPass = auditReport.hard_fail_count === 0;
-    const scenarioResults = await validateFoundationScenarios(mechanismsPass, auditPass, true);
-    const allPass = scenarioResults.every((s) => s.status === "PASS");
-    const isJson = process.argv.includes("--json");
-    if (isJson) {
-        const problemMatrix = validateFoundationProblemMatrix(cwd);
-        const problemAllPass = problemMatrix.every((p) => Object.values(p.dimensions).every((d) => d.status === "PASS"));
-        userInfo(JSON.stringify({
-            mechanisms_pass: mechanismsPass,
-            audit_pass: auditPass,
-            all_pass: allPass && problemAllPass,
-            problem_matrix_count: problemMatrix.length,
-            problem_matrix: problemMatrix,
-            scenarios: scenarioResults,
-        }, null, 2));
-    }
-    else {
-        for (const s of scenarioResults) {
-            const icon = s.status === "PASS" ? "✓" : "✗";
-            userInfo(`${icon} ${s.scenario_id}: ${s.scenario_name} — ${s.status}`);
-            for (const r of s.rules) {
-                const ri = r.status === "PASS" ? "  ✓" : "  ✗";
-                userInfo(`${ri} ${r.rule}: ${r.evidence}`);
-            }
-        }
-        userInfo(allPass ? "\n所有场景通过" : "\n部分场景失败");
-    }
-    process.exit(allPass ? 0 : 1);
-}
-/**
- * 新增问题/issue 演进门控 — problem-54 真实消费入口。
- * 用法: soloforge validate-new-issue --title="问题标题" --batch=2 [--json]
- */
-async function cmdValidateNewIssue() {
-    debug("CLI", "执行 cmdValidateNewIssue");
-    const title = getArgValue("--title") ?? "";
-    const batchStr = getArgValue("--batch");
-    const batch = batchStr ? parseInt(batchStr, 10) : 0;
-    const isJson = args.includes("--json");
-    if (!title) {
-        userError("❌ 错误: --title 必须提供");
-        process.exit(1);
-    }
-    const { performEvolutionGate, checkDuplicateIssue, createNewIssueRegressionGate, } = await import("../engine/evolution_regression_gate.js");
-    // 从 implementation_roadmap_registry 加载真实已有问题
-    const { listAllProblems } = await import("../engine/implementation_roadmap_registry.js");
-    const allProblems = listAllProblems();
-    // 精确重复检测: label 精确匹配（不子串），title 语义包含，id 精确匹配
-    const lower = title.toLowerCase();
-    const matchedProblemMap = new Map();
-    for (const p of allProblems) {
-        let matched = false;
-        // id 精确匹配
-        if (p.id.toLowerCase() === lower)
-            matched = true;
-        // label 精确匹配
-        if (p.label.toLowerCase() === lower)
-            matched = true;
-        // label 前缀匹配: "问题四十二" 匹配 "问题四十二" 等
-        if (p.label.toLowerCase().startsWith(lower + "("))
-            matched = true;
-        // 完整 title 的包含匹配（title 是长描述，子串匹配合理）
-        if (lower.length >= 2 && p.title.toLowerCase().includes(lower))
-            matched = true;
-        // 输入包含完整 title（输入更长时）
-        if (lower.length >= 4 && p.title.length >= 4 && lower.includes(p.title.toLowerCase()))
-            matched = true;
-        if (matched) {
-            matchedProblemMap.set(p.id, { id: p.id, label: p.label, title: p.title });
-        }
-    }
-    const deduplicatedIds = [...matchedProblemMap.keys()];
-    const matchedDetails = [...matchedProblemMap.values()];
-    // 稳定 slug: 基于标题哈希而非 Date.now
-    const titleSlug = title
-        .toLowerCase()
-        .replace(/[^a-z0-9一-鿿]+/g, "-")
-        .replace(/^-|-$/g, "")
-        .slice(0, 40);
-    const hashSuffix = crypto.createHash("sha256").update(title).digest("hex").slice(0, 8);
-    const candidateId = `problem-new-${titleSlug}-${hashSuffix}`;
-    const gate = createNewIssueRegressionGate({
-        issue_candidate_id: candidateId,
-        candidate_title: title,
-    });
-    // 重复检测 — 写入去重后的 ID 列表
-    gate.duplicate_check.possible_duplicates = deduplicatedIds;
-    // 演进门控
-    const result = performEvolutionGate(gate);
-    const output = {
-        title,
-        batch,
-        candidate_id: candidateId,
-        existing_issues_checked: allProblems.length,
-        duplicate_detected: gate.duplicate_check.possible_duplicates.length > 0,
-        duplicates: [...new Set(gate.duplicate_check.possible_duplicates)],
-        matched_duplicate_details: matchedDetails,
-        gate_status: result.gate_status,
-        can_proceed: result.allowed,
-        reasons: result.reasons,
-    };
-    if (isJson) {
-        userInfo(JSON.stringify(output, null, 2));
-    }
-    else {
-        userInfo(`需求演进检查: ${output.gate_status}`);
-        userInfo(`  已检查 ${allProblems.length} 个已有功能记录`);
-        if (output.duplicate_detected) {
-            userInfo(`  ⚠ 重复检测: 发现 ${output.duplicates.join(", ")}`);
-            for (const d of matchedDetails) {
-                userInfo(`    - ${d.id}: ${d.label} — ${d.title}`);
-            }
-        }
-        if (result.reasons.length > 0) {
-            userInfo(`  原因:`);
-            for (const r of result.reasons)
-                userInfo(`    - ${r}`);
-        }
-        if (output.can_proceed) {
-            userInfo(`  ✓ 可继续: 需求新增已通过演进检查 (ID: ${candidateId})`);
-        }
-    }
-    if (!output.can_proceed) {
-        process.exit(1);
-    }
-}
-async function cmdStatus() {
-    debug("CLI", "执行 cmdStatus");
-    const projectPath = resolveProjectPath();
-    const { config, source } = await resolveProjectConfig(projectPath);
-    userInfo(`SoloForge 状态: ${projectPath}`);
-    userInfo(`  配置来源: ${source === "config_file" ? "config.yaml" : "自动推断"}`);
-    userInfo(`  产品: ${config.product_profile}`);
-    userInfo(`  后端: ${config.tech_stack.backend.framework || "未配置"}`);
-    userInfo(`  前端: ${config.tech_stack.frontend.framework || "未配置"}`);
-    // 逐字段配置优先级状态
-    try {
-        const { resolutions, entries } = await resolveCurrentProjectConfigReports(projectPath);
-        if (resolutions.length > 0) {
-            userInfo("");
-            userInfo("  字段解析状态:");
-            for (const r of resolutions) {
-                const stale = r.stale_warning ? " ⚠️ stale" : "";
-                const conflict = r.conflict_report ? " ⚠️ conflict" : "";
-                userInfo(`    ${r.field_path}: ${JSON.stringify(r.resolved_value)} (${r.source}${stale}${conflict})`);
-            }
-        }
-        const schemaPath = path.join(projectPath, ".soloforge", "config.evidence.json");
-        if (fss.existsSync(schemaPath)) {
-            try {
-                const raw = JSON.parse(fss.readFileSync(schemaPath, "utf-8"));
-                userInfo(`  evidence: schema_version=${raw.schema_version ?? 1}, ${entries.length} 条`);
-            }
-            catch {
-                userInfo("  evidence: 无法解析");
-            }
-        }
-        else if (source === "config_file") {
-            userInfo("  evidence: ⚠️ config.evidence.json 缺失");
-        }
-    }
-    catch { }
-    // Evidence 警告
-    const evidenceWarnings = await checkEvidenceWarnings(projectPath);
-    for (const w of evidenceWarnings) {
-        userInfo(`  ⚠️  evidence: ${w}`);
-    }
-    const knowledgeDir = getProjectKnowledgeDir(config);
-    if (fss.existsSync(knowledgeDir)) {
-        const { KnowledgeIndexManager } = await import("../knowledge/index_manager.js");
-        const index = new KnowledgeIndexManager(config, { watch: false });
-        try {
-            await index.build();
-            const entries = index.getAllEntries();
-            userInfo(`  知识: ${entries.global.length} 全局 + ${entries.project.length} 项目`);
-        }
-        finally {
-            await index.close();
-        }
-    }
-    else {
-        userInfo("  知识: 未初始化");
-    }
-    // 导航摘要（消费同一规划模块，包含阻断项和下一步）
-    try {
-        const { planNextAction } = await import("../engine/next_action_planner.js");
-        const navigation = await planNextAction(projectPath);
-        userInfo(`  阶段: ${navigation.project_stage}${navigation.task_stage ? ` / ${navigation.task_stage}` : ""}`);
-        if (navigation.blocking_reasons.length > 0) {
-            userInfo(`  导航阻断: ${navigation.blocking_reasons.join("; ")}`);
-        }
-        if (navigation.confirmation_decisions.auto_resolvable.length > 0) {
-            userInfo(`  可自动处理: ${navigation.confirmation_decisions.auto_resolvable.map((item) => item.command_hint ?? item.title_zh).join(" / ")}`);
-        }
-        if (navigation.confirmation_decisions.must_confirm.length > 0) {
-            userInfo(`  必须确认: ${navigation.confirmation_decisions.must_confirm.map((item) => item.title_zh).join(" / ")}`);
-        }
-        userInfo(`  下一步: ${navigation.work_package?.goal_zh ?? navigation.recommended_prompt_zh}`);
-    }
-    catch (e) {
-        userInfo(`  ⚠ 导航摘要异常: ${e instanceof Error ? e.message : String(e)}`);
-    }
-}
-async function interactiveConfig(projectPath) {
-    debug("CLI", "执行 interactiveConfig");
-    if (!process.stdin.isTTY)
-        return undefined;
-    const readline = await import("node:readline");
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const ask = (q) => new Promise((res) => rl.question(q, res));
-    const name = await ask("项目名称: ") || "my-project";
-    const product = await ask("产品类型 (saas/b2b-internal/b2c): ") || "default";
-    const backendFramework = await ask("后端框架 (spring-boot): ") || "spring-boot";
-    const frontendFramework = await ask("前端框架 (react): ") || "react";
-    rl.close();
-    const draft = {
-        name,
-        tech_stack: {
-            backend: { lang: backendFramework === "go" ? "go" : "java", framework: backendFramework, version: "" },
-            frontend: { lang: "typescript", framework: frontendFramework, version: "" },
-        },
-        product_profile: product,
-        build_commands: {
-            backend: blueprintBackendCommands(backendFramework),
-            frontend: blueprintFrontendCommands(frontendFramework),
-        },
-        scope: { backend: ["src/"], frontend: ["src/"] },
-        advisory_notes: [],
-        confidence: "high",
-    };
-    const src = "confirmed";
-    const evidence = {
-        schema_version: 1,
-        generated_at: new Date().toISOString(),
-        mode: "interactive",
-        project_root: projectPath,
-        fields: {
-            "name": { value: name, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "tech_stack.backend": { value: draft.tech_stack.backend, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "tech_stack.frontend": { value: draft.tech_stack.frontend, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "build_commands.backend": { value: draft.build_commands.backend, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "build_commands.frontend": { value: draft.build_commands.frontend, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "product_profile": { value: product, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "scope.backend": { value: draft.scope.backend, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-            "scope.frontend": { value: draft.scope.frontend, confidence: "high", confidence_source: src, evidence: ["--interactive input"] },
-        },
-    };
-    return { draft, evidence };
-}
-function cmdVersion() {
-    debug("CLI", "执行 cmdVersion");
-    // dist/bin/soloforge.js → dist/package.json (local) 或 package.json (global npm)
-    const pkgPath = path.resolve(import.meta.dirname, "..", "package.json");
-    try {
-        const pkg = JSON.parse(fss.readFileSync(pkgPath, "utf-8"));
-        userInfo("SoloForge v" + pkg.version);
-    }
-    catch {
-        // 回退: 从 dist 同级目录查找
-        const altPath = path.resolve(import.meta.dirname, "..", "..", "package.json");
-        const pkg = JSON.parse(fss.readFileSync(altPath, "utf-8"));
-        userInfo("SoloForge v" + pkg.version);
-    }
-}
-async function cmdNext() {
-    debug("CLI", "执行 cmdNext");
-    const projectPath = resolveProjectPath();
-    const isJson = args.includes("--json");
-    const writeSnapshot = args.includes("--write-snapshot");
-    const { planNextAction } = await import("../engine/next_action_planner.js");
-    const plan = await planNextAction(projectPath);
-    if (isJson) {
-        // JSON 模式: 纯 JSON 到 stdout，无日志污染
-        const wp = plan.work_package;
-        const output = {
-            project_stage: plan.project_stage,
-            task_stage: plan.task_stage,
-            confidence: plan.confidence,
-            stage_evidence: plan.stage_evidence,
-            blocking_reasons: plan.blocking_reasons,
-            confirmation_decisions: plan.confirmation_decisions,
-            warnings: plan.warnings,
-            recommended_commands: plan.recommended_commands,
-            recommended_prompt: plan.recommended_prompt_zh,
-            project_knowledge_context: plan.project_knowledge_context,
-            disallowed_next_actions: plan.disallowed_actions.map((da) => ({
-                rule_id: da.rule_id,
-                blocked_actions: da.blocked_actions,
-                reason_zh: da.reason_zh,
-            })),
-            work_package: wp ? {
-                id: wp.id,
-                goal: wp.goal_zh,
-                input_files: wp.input_files,
-                must_read: wp.must_read,
-                forbidden_changes: wp.forbidden_changes,
-                expected_outputs: wp.expected_outputs,
-                acceptance_commands: wp.acceptance_commands,
-                user_confirmation_points: wp.user_confirmation_points,
-                rollback_or_fallback: wp.rollback_or_fallback,
-            } : null,
-        };
-        process.stdout.write(JSON.stringify(output, null, 2) + "\n");
-    }
-    else {
-        // 人类可读输出
-        userInfo(`\n项目阶段: ${plan.project_stage}`);
-        if (plan.task_stage) {
-            userInfo(`任务阶段: ${plan.task_stage}`);
-        }
-        else {
-            userInfo("任务阶段: 无活跃任务");
-        }
-        userInfo(`置信度: ${plan.confidence}`);
-        if (plan.stage_evidence.length > 0) {
-            userInfo(`\n判断依据:`);
-            for (const ev of plan.stage_evidence) {
-                userInfo(`  - ${ev}`);
-            }
-        }
-        if (plan.warnings.length > 0) {
-            userInfo(`\n提示:`);
-            for (const warning of plan.warnings) {
-                userInfo(`  - [${warning.code}] ${warning.message_zh}`);
-            }
-        }
-        userInfo(`\n确认分级:`);
-        userInfo(`  必须确认: ${plan.confirmation_decisions.must_confirm.length}`);
-        for (const item of plan.confirmation_decisions.must_confirm) {
-            userInfo(`    - ${item.title_zh}: ${item.reason_zh}`);
-            if (item.command_hint)
-                userInfo(`      命令: ${item.command_hint}`);
-            userInfo(`      不确认影响: ${item.if_unconfirmed_zh}`);
-        }
-        userInfo(`  建议确认: ${plan.confirmation_decisions.should_confirm.length}`);
-        for (const item of plan.confirmation_decisions.should_confirm) {
-            userInfo(`    - ${item.title_zh}: ${item.reason_zh}`);
-            if (item.command_hint)
-                userInfo(`      命令: ${item.command_hint}`);
-        }
-        userInfo(`  可自动处理: ${plan.confirmation_decisions.auto_resolvable.length}`);
-        for (const item of plan.confirmation_decisions.auto_resolvable) {
-            userInfo(`    - ${item.title_zh}`);
-            if (item.command_hint)
-                userInfo(`      命令: ${item.command_hint}`);
-        }
-        userInfo(`  推荐处理: ${plan.confirmation_decisions.recommended_action}`);
-        if (plan.project_knowledge_context && plan.project_knowledge_context.total > 0) {
-            userInfo(`\n项目规则上下文:`);
-            userInfo(`  项目知识: ${plan.project_knowledge_context.total} 条，hard_fail: ${plan.project_knowledge_context.hard_fail_count}`);
-            if (plan.project_knowledge_context.selected.length > 0) {
-                userInfo("  下一步会优先参考:");
-                for (const item of plan.project_knowledge_context.selected) {
-                    userInfo(`    - ${item.name} (${item.rel_path}, ${item.enforcement ?? item.consumption})`);
-                    if (item.reason_zh)
-                        userInfo(`      原因: ${item.reason_zh}`);
-                    if (item.verification_command)
-                        userInfo(`      复验: ${item.verification_command}`);
-                }
-            }
-            if (plan.project_knowledge_context.blocked && plan.project_knowledge_context.blocked.length > 0) {
-                userInfo("  必须先处理:");
-                for (const item of plan.project_knowledge_context.blocked) {
-                    userInfo(`    - ${item.name} (${item.rel_path})`);
-                    userInfo(`      原因: ${item.reason_zh}`);
-                    if (item.recovery)
-                        userInfo(`      恢复: ${item.recovery}`);
-                }
-            }
-        }
-        // 陈旧任务
-        if (plan.stale_task?.is_stale) {
-            userInfo(`\n⚠️  检测到陈旧任务: ${plan.stale_task.reason_zh}`);
-            userInfo(`  任务 ID: ${plan.stale_task.task_id}`);
-            userInfo(`  建议操作: ${plan.stale_task.suggested_resolutions.join(" / ")}`);
-            userInfo(`  ⚠️  不要绕过 SoloForge 状态直接操作`);
-        }
-        // 阻断项
-        if (plan.blocking_reasons.length > 0) {
-            userInfo(`\n阻断项:`);
-            for (const r of plan.blocking_reasons) {
-                userInfo(`  - ${r}`);
-            }
-        }
-        // 工作包
-        if (plan.work_package) {
-            const wp = plan.work_package;
-            userInfo(`\n下一步: ${wp.goal_zh}`);
-            userInfo(`  描述: ${wp.description_zh}`);
-            if (wp.tool_name) {
-                userInfo(`  工具: ${wp.tool_name}`);
-            }
-            if (wp.must_read.length > 0) {
-                userInfo(`  必读文件:`);
-                for (const f of wp.must_read)
-                    userInfo(`    - ${f}`);
-            }
-            if (wp.forbidden_changes.length > 0) {
-                userInfo(`  禁止操作:`);
-                for (const f of wp.forbidden_changes)
-                    userInfo(`    - ${f}`);
-            }
-            if (wp.expected_outputs.length > 0) {
-                userInfo(`  预期产出:`);
-                for (const e of wp.expected_outputs)
-                    userInfo(`    - ${e}`);
-            }
-            if (wp.acceptance_commands.length > 0) {
-                userInfo(`  验收命令:`);
-                for (const c of wp.acceptance_commands)
-                    userInfo(`    - ${c}`);
-            }
-            if (wp.user_confirmation_points.length > 0) {
-                userInfo(`  工作包确认点（是否阻塞以上方确认分级为准）:`);
-                for (const u of wp.user_confirmation_points)
-                    userInfo(`    - ${u}`);
-            }
-            if (wp.rollback_or_fallback.length > 0) {
-                userInfo(`  失败回退:`);
-                for (const r of wp.rollback_or_fallback)
-                    userInfo(`    - ${r}`);
-            }
-        }
-        // 推荐命令
-        if (plan.recommended_commands.length > 0) {
-            userInfo(`\n推荐命令:`);
-            for (const c of plan.recommended_commands) {
-                userInfo(`  ${c}`);
-            }
-        }
-        // 禁止动作
-        if (plan.disallowed_actions.length > 0) {
-            userInfo(`\n禁止动作:`);
-            for (const da of plan.disallowed_actions) {
-                userInfo(`  [${da.rule_id}] ${da.blocked_actions.join(", ")}: ${da.reason_zh}`);
-            }
-        }
-        // 推荐给 AI 的指令
-        userInfo(`\n推荐指令: ${plan.recommended_prompt_zh}`);
-    }
-    // 写入快照（只在显式 --write-snapshot 时）
-    if (writeSnapshot) {
-        const snapshotPath = path.join(projectPath, ".soloforge", "navigation-snapshot.json");
-        const snapshot = {
-            plan_id: plan.plan_id,
-            generated_at: plan.generated_at,
-            project_stage: plan.project_stage,
-            task_stage: plan.task_stage,
-            current_task_id: plan.current_task_id,
-            work_package: plan.work_package,
-        };
-        fss.mkdirSync(path.join(projectPath, ".soloforge"), { recursive: true });
-        fss.writeFileSync(snapshotPath, JSON.stringify(snapshot, null, 2));
-        if (!isJson) {
-            userInfo(`\n导航快照已写入: ${snapshotPath}`);
-        }
-    }
-}
-async function cmdStage() {
-    debug("CLI", "执行 cmdStage");
-    const projectPath = resolveProjectPath();
-    const explain = args.includes("--explain");
-    const isJson = args.includes("--json");
-    const { detectProjectStage, explainProjectStage } = await import("../engine/project_stage_detector.js");
-    const { detectTaskStage, explainTaskStage } = await import("../engine/task_stage_detector.js");
-    const projectStage = await detectProjectStage(projectPath);
-    // 加载当前任务
-    let taskStage = null;
-    let taskId = null;
-    try {
-        const { TaskContextManager } = await import("../engine/task_context.js");
-        const stateDir = path.join(projectPath, ".soloforge", "state");
-        if (fss.existsSync(stateDir)) {
-            const manager = new TaskContextManager(stateDir);
-            const ctx = await manager.getCurrentTask();
-            if (ctx) {
-                taskStage = detectTaskStage(ctx);
-                taskId = ctx.task_id;
-            }
-        }
-    }
-    catch { }
-    if (isJson) {
-        const projExplanation = explainProjectStage(projectStage);
-        process.stdout.write(JSON.stringify({
-            project: projExplanation,
-            task: taskStage ? explainTaskStage(taskStage) : null,
-            task_id: taskId,
-        }, null, 2) + "\n");
-        return;
-    }
-    userInfo(`\n项目阶段: ${projectStage}`);
-    if (explain) {
-        const projExplanation = explainProjectStage(projectStage);
-        userInfo(`  ${projExplanation.description_zh}`);
-        userInfo(`  必要条件: ${projExplanation.required_evidence.join(", ") || "无"}`);
-        userInfo(`  下一步可能: ${projExplanation.next_possible_stages.join(", ")}`);
-    }
-    if (taskStage) {
-        userInfo(`\n任务阶段: ${taskStage} (${taskId ?? "unknown"})`);
-        if (explain) {
-            const taskExplanation = explainTaskStage(taskStage);
-            userInfo(`  ${taskExplanation.description_zh}`);
-            userInfo(`  必要条件: ${taskExplanation.required_evidence.join(", ")}`);
-            userInfo(`  下一步可能: ${taskExplanation.next_possible_stages.join(", ")}`);
-        }
-    }
-    else {
-        userInfo("\n当前无活跃任务");
-    }
-}
-async function cmdCleanup() {
-    debug("CLI", "执行 cmdCleanup");
-    const dryRun = !args.includes("--apply");
-    const staleOnly = args.includes("--stale");
-    const projectPath = process.cwd();
-    const stateDir = path.join(projectPath, ".soloforge", "state");
-    let hasError = false;
-    userInfo(`SoloForge 清理: ${projectPath}`);
-    userInfo(`  模式: ${dryRun ? "dry-run（仅评估）" : "⚠️ 实际清理"}`);
-    if (staleOnly) {
-        try {
-            const { detectStaleCurrentTask, archiveStaleCurrentPointer } = await import("../engine/stale_current_task_detector.js");
-            const stale = await detectStaleCurrentTask(stateDir);
-            userInfo("");
-            userInfo("  陈旧 current-task 检测:");
-            if (!stale.is_stale || !stale.task_id) {
-                userInfo("    未发现陈旧指针");
-                return;
-            }
-            userInfo(`    陈旧任务: ${stale.task_id}`);
-            userInfo(`    原因: ${stale.reason_zh}`);
-            if (dryRun) {
-                userInfo("    处理: dry-run，仅提示；使用 --apply 归档指针");
-                return;
-            }
-            const archived = await archiveStaleCurrentPointer(stateDir, stale.task_id);
-            if (!archived) {
-                userError("  ❌ 陈旧指针归档失败");
-                process.exit(1);
-            }
-            userInfo("    处理: 已归档 current-task 指针，任务文件未删除");
-            return;
-        }
-        catch (e) {
-            userError(`  ❌ 陈旧 current-task 检测失败: ${e.message}`);
-            process.exit(1);
-        }
-    }
-    // 收集所有 evidence 引用来源：task-*.json 中的 evidence 文件名 / evidence id
-    const referencedEvidenceIds = new Set();
-    // 扫描 task context 文件中的 evidence 引用
-    if (fss.existsSync(stateDir)) {
-        for (const f of fss.readdirSync(stateDir).filter((f) => f.startsWith("task-") && f.endsWith(".json"))) {
-            try {
-                const content = fss.readFileSync(path.join(stateDir, f), "utf-8");
-                const ctx = JSON.parse(content);
-                // 从 verification_evidence 收集引用
-                if (ctx.verification_evidence && typeof ctx.verification_evidence === "object") {
-                    for (const [key, val] of Object.entries(ctx.verification_evidence)) {
-                        if (typeof val === "string")
-                            referencedEvidenceIds.add(val);
-                        referencedEvidenceIds.add(key);
-                    }
-                }
-                // 从 artifacts 的 evidence_refs 收集
-                if (Array.isArray(ctx.output_artifacts)) {
-                    for (const art of ctx.output_artifacts) {
-                        if (art.evidence_refs && Array.isArray(art.evidence_refs)) {
-                            for (const ref of art.evidence_refs)
-                                referencedEvidenceIds.add(ref);
-                        }
-                        if (art.artifact_id)
-                            referencedEvidenceIds.add(art.artifact_id);
-                    }
-                }
-                // 从 delivery_report 收集
-                if (ctx.delivery_report && typeof ctx.delivery_report === "object") {
-                    const dr = ctx.delivery_report;
-                    if (dr.evidence_refs && Array.isArray(dr.evidence_refs)) {
-                        for (const ref of dr.evidence_refs)
-                            referencedEvidenceIds.add(ref);
-                    }
-                }
-                // 从 governance_report 收集
-                if (ctx.governance_report && typeof ctx.governance_report === "string") {
-                    referencedEvidenceIds.add(ctx.governance_report);
-                }
-            }
-            catch {
-                // 跳过不可解析文件
-            }
-        }
-    }
-    // 1. TaskContext 清理（使用 retention_policy）
-    if (fss.existsSync(stateDir)) {
-        try {
-            const { TaskContextManager } = await import("../engine/task_context.js");
-            const mgr = new TaskContextManager(stateDir);
-            const result = await mgr.cleanup(dryRun);
-            userInfo("");
-            userInfo("  TaskContext 清理:");
-            userInfo(`    已清理: ${result.removed} 条`);
-            userInfo(`    受保护（被引用不可删除）: ${result.protected} 条`);
-            userInfo(`    禁止内容检出: ${result.forbidden_content_hits.length > 0 ? result.forbidden_content_hits.join("; ") : "无"}`);
-            userInfo(`    dry_run: ${result.dry_run}`);
-            if (result.forbidden_content_hits.length > 0) {
-                userError(`  ❌ TaskContext 包含禁止内容，清理中止`);
-                hasError = true;
-            }
-        }
-        catch (e) {
-            userError(`  ❌ TaskContext 清理失败: ${e.message}`);
-            process.exit(1);
-        }
-    }
-    else {
-        userInfo("  TaskContext: 状态目录不存在，跳过");
-    }
-    // 2. Evidence 文件清理（真实引用扫描）
-    const evidenceDir = path.join(projectPath, ".soloforge");
-    if (fss.existsSync(evidenceDir)) {
-        try {
-            const { evaluateCleanup, checkForbiddenContent } = await import("../engine/retention_policy.js");
-            const evidenceFiles = fss.readdirSync(evidenceDir)
-                .filter((f) => f.endsWith(".json") && !f.startsWith("config."))
-                .map((f) => {
-                const fp = path.join(evidenceDir, f);
-                const stat = fss.statSync(fp);
-                const ageDays = Math.max(0, (Date.now() - stat.mtimeMs) / (24 * 60 * 60 * 1000));
-                const content = fss.readFileSync(fp, "utf-8");
-                const forbiddenHits = checkForbiddenContent("evidence", content);
-                // 真实引用检查: evidence 文件名或内容中的 id 出现在引用集合中
-                const isReferenced = referencedEvidenceIds.has(f) || referencedEvidenceIds.has(f.replace(/\.json$/, ""));
-                return { name: f, age_days: ageDays, is_referenced: isReferenced, forbidden: forbiddenHits };
-            });
-            const records = evidenceFiles.map(e => ({ id: e.name, age_days: e.age_days, is_referenced: e.is_referenced }));
-            const result = evaluateCleanup("evidence", records, dryRun);
-            userInfo("");
-            userInfo("  Evidence 清理:");
-            userInfo(`    总文件: ${result.total_records}`);
-            userInfo(`    可清理: ${result.eligible_for_cleanup}`);
-            userInfo(`    受保护: ${result.protected_records}`);
-            userInfo(`    dry_run: ${result.dry_run}`);
-            if (result.cleanup_candidates.length > 0) {
-                userInfo(`    清理候选: ${result.cleanup_candidates.join(", ")}`);
-            }
-            const forbiddenFiles = evidenceFiles.filter(e => e.forbidden.length > 0);
-            if (forbiddenFiles.length > 0) {
-                userInfo("    ❌ 禁止内容检出:");
-                for (const f of forbiddenFiles) {
-                    userInfo(`      ${f.name}: ${f.forbidden.join(", ")}`);
-                }
-                hasError = true;
-            }
-        }
-        catch (e) {
-            userError(`  ❌ Evidence 清理失败: ${e.message}`);
-            process.exit(1);
-        }
-    }
-    // 3. 列出所有保留策略
-    try {
-        const { listRetentionPolicies } = await import("../engine/retention_policy.js");
-        const policies = listRetentionPolicies();
-        userInfo("");
-        userInfo("  保留策略:");
-        for (const p of policies) {
-            userInfo(`    ${p.policy_id}: ${p.record_type}, 最大 ${p.max_age_days} 天 / ${p.max_count} 条, dry_run_default=${p.dry_run_default}`);
-        }
-    }
-    catch (e) {
-        userError(`  ❌ 保留策略加载失败: ${e.message}`);
-        process.exit(1);
-    }
-    if (hasError)
-        process.exit(1);
-}
-main().catch((e) => { internalWarn("CLI", "启动失败:", e); process.exit(1); });
-function getArgValue(flag) {
-    // 支持 --flag=value 格式
-    const eqPrefix = flag + "=";
-    const eqIdx = args.findIndex((a) => a.startsWith(eqPrefix));
-    if (eqIdx !== -1) {
-        return args[eqIdx].slice(eqPrefix.length) || undefined;
-    }
-    const idx = args.indexOf(flag);
-    if (idx === -1 || idx + 1 >= args.length)
-        return undefined;
-    const result = args[idx + 1];
-    if (result.startsWith("--"))
-        return undefined;
-    return result;
-}
-async function cmdAuditTemplateVisibility() {
-    const projectPath = process.env.SOLOFORGE_PROJECT ?? process.cwd();
-    const { auditStandardAssetCoverage } = await import("../engine/standard_asset_coverage.js");
-    const { listBuiltinConsumableAssets } = await import("../engine/consumable_asset_registry.js");
-    const { listTemplateAssetContracts, auditContractCoverage } = await import("../engine/template_asset_contract_registry.js");
-    const { userInfo, userJson } = await import("../engine/logger.js");
-    // 使用权威合同注册表作为单一数据源
-    const contracts = listTemplateAssetContracts();
-    const registeredAssets = listBuiltinConsumableAssets();
-    const consumablePaths = new Set(registeredAssets.map((a) => a.path));
-    const ownerMap = new Map(contracts.map((c) => [c.path, c.owner_mechanism_id]));
-    const consumerMap = new Map(contracts.map((c) => [c.path, [c.mainline_consumer, c.validation_entrypoint].filter(Boolean)]));
-    const visibilityMap = new Map(contracts.map((c) => [c.path, c.asset_visibility]));
-    // 运行覆盖审计（使用真实合同数据）
-    const report = auditStandardAssetCoverage(projectPath, consumablePaths, ownerMap, consumerMap, visibilityMap);
-    // 合同覆盖统计
-    const coverageReport = auditContractCoverage(projectPath);
-    // 可见性统计（从权威合同直接计算）
-    const internalCount = contracts.filter((c) => c.asset_visibility === "soloforge_internal" || c.asset_visibility === "scaffold_only").length;
-    const userVisibleCount = contracts.filter((c) => c.user_visible).length;
-    // 输出报告
-    const isJson = args.includes("--json");
-    const result = {
-        total_assets: report.total_assets,
-        registered_contracts: coverageReport.total_contracts,
-        contract_covered: coverageReport.contract_covered,
-        uncovered_assets: coverageReport.uncovered,
-        user_visible_count: userVisibleCount,
-        internal_count: internalCount,
-        unknown_visibility: coverageReport.visibility_unknown,
-        conflict_count: 0,
-        missing_bearer: report.missing_standard_bearer,
-        missing_revalidation: report.missing_revalidation,
-        missing_consumer: report.missing_consumer,
-        missing_owner: report.missing_owner,
-        unregistered: report.unregistered_assets,
-        consumption_evidence_verified: coverageReport.consumption_evidence_verified,
-        consumption_evidence_failures: coverageReport.consumption_evidence_failures,
-    };
-    if (isJson) {
-        userJson(JSON.stringify(result, null, 2));
-    }
-    else {
-        userInfo("═══ 模板资产可见性审计报告 ═══");
-        userInfo(`总资产数:       ${report.total_assets}`);
-        userInfo(`注册合同数:     ${coverageReport.total_contracts}（包含非文件运行时资产）`);
-        userInfo(`合同覆盖:       ${coverageReport.contract_covered}`);
-        userInfo(`未覆盖:         ${coverageReport.uncovered}`);
-        userInfo(`用户可见:       ${userVisibleCount}`);
-        userInfo(`内部资产:       ${internalCount}`);
-        userInfo(`未知可见性:     ${coverageReport.visibility_unknown}`);
-        userInfo(`缺标准承载:     ${report.missing_standard_bearer}`);
-        userInfo(`缺复验入口:     ${report.missing_revalidation}`);
-        userInfo(`缺消费者:       ${report.missing_consumer}`);
-        userInfo(`缺 owner:       ${report.missing_owner}`);
-        userInfo(`未注册:         ${report.unregistered_assets}`);
-        userInfo(`消费证据验证:   ${coverageReport.consumption_evidence_verified ? "通过" : "失败"}`);
-        for (const failure of coverageReport.consumption_evidence_failures) {
-            userInfo(`  - ${failure}`);
-        }
-    }
-}
-async function cmdAuditProjectKnowledge() {
-    const projectPathArg = getArgValue("--project-path");
-    const projectPath = projectPathArg ? path.resolve(projectPathArg) : (process.env.SOLOFORGE_PROJECT ?? process.cwd());
-    const { auditProjectKnowledge } = await import("../engine/project_knowledge_contract.js");
-    const { userInfo, userJson } = await import("../engine/logger.js");
-    const isJson = args.includes("--json");
-    const { config } = await resolveProjectConfig(projectPath, { quiet: isJson });
-    const report = auditProjectKnowledge(projectPath, config);
-    if (isJson) {
-        userJson(JSON.stringify(report, null, 2));
-        return;
-    }
-    userInfo(`用户项目知识审计: ${projectPath}`);
-    userInfo(`  总数: ${report.total}`);
-    userInfo(`  用户自建: ${report.user_authored}`);
-    userInfo(`  内置同步: ${report.builtin_synced}`);
-    userInfo(`  用户修改内置: ${report.user_modified_builtin}`);
-    userInfo(`  冲突: ${report.conflict}`);
-    userInfo(`  hard_rule: ${report.hard_rule}`);
-    userInfo(`  injectable: ${report.injectable}`);
-    userInfo(`  index_only: ${report.index_only}`);
-    userInfo(`  hard_fail: ${report.hard_fail_count}`);
-    userInfo(`  warning: ${report.warning_count}`);
-    for (const asset of report.assets) {
-        userInfo(`  - ${asset.rel_path} (${asset.identity}/${asset.consumption})`);
-        userInfo(`    创建: ${asset.evidence.created_by}；索引: ${asset.evidence.indexed_by}`);
-        if (asset.lifecycle_stages.length > 0)
-            userInfo(`    阶段: ${asset.lifecycle_stages.join(", ")}`);
-        if (asset.path_patterns.length > 0)
-            userInfo(`    路径: ${asset.path_patterns.join(", ")}`);
-        if (asset.traceability_ids.length > 0)
-            userInfo(`    追踪: ${asset.traceability_ids.join(", ")}`);
-        if (asset.verification_commands.length > 0)
-            userInfo(`    复验: ${asset.verification_commands.join(" / ")}`);
-        if (asset.evidence.last_consumed_at) {
-            userInfo(`    最近消费: ${asset.evidence.last_consumption_consumer}/${asset.evidence.last_consumption_action} ${asset.evidence.last_consumed_task} @ ${asset.evidence.last_consumed_at}`);
-        }
-        for (const finding of asset.findings) {
-            const mark = finding.severity === "hard_fail" ? "❌" : finding.severity === "warning" ? "⚠️" : "ℹ️";
-            userInfo(`    ${mark} [${finding.code}] ${finding.message_zh}`);
-        }
-    }
-    if (report.recent_consumption.length > 0) {
-        userInfo("  最近消费证据:");
-        for (const item of report.recent_consumption.slice(0, 10)) {
-            userInfo(`    - ${item.rel_path ?? item.asset_id}: ${item.consumer}/${item.action ?? "unknown"} ${item.lifecycle_stage ?? "unknown_stage"} ${item.task_id_or_route} ${item.decision ?? ""}`);
-        }
-    }
-    if (report.recommended_next_steps.length > 0) {
-        userInfo("  下一步:");
-        for (const step of report.recommended_next_steps)
-            userInfo(`    - ${step}`);
-    }
-}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(EXIT.GENERAL);
+});
 //# sourceMappingURL=soloforge.js.map