soloforge 1.2.20 → 1.3.1

package/dist/bin/soloforge.js

@@ -16,10 +16,11 @@ import { cmdConfigResolve, cmdConfigExplain, cmdConfigConfirm, cmdConfigUnset, l
 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 } from "../engine/debug_log.js";
+import { debugLog, debug, userInfo, userWarn, userError, internalWarn, jsonSafeError, initLoggerFromEnv } from "../engine/logger.js";
 const command = process.argv[2];
 const args = process.argv.slice(3);
 async function main() {
+    initLoggerFromEnv();
     switch (command) {
         case "init":
             if (args.includes("--auto")) {
@@ -59,8 +60,38 @@ async function main() {
         case "audit-template-mechanisms":
             await cmdAuditTemplateMechanisms();
             break;
+        case "audit-design-artifacts":
+            await cmdAuditDesignArtifacts();
+            break;
+        case "upgrade-design-artifacts":
+            await cmdUpgradeDesignArtifacts();
+            break;
         case "validate-batch1":
-            await cmdValidateBatch1();
+            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;
+        case "sync-templates":
+            await cmdSyncTemplates();
+            break;
+        case "sync-adapters":
+            await cmdSyncAdapters();
+            break;
+        case "migrate":
+            await cmdMigrate();
+            break;
+        case "validate-new-issue":
+            await cmdValidateNewIssue();
             break;
         case "generate-trae":
             await cmdGenerateTrae();
@@ -89,20 +120,23 @@ async function main() {
                     await cmdConfigUnset();
                     break;
                 default:
-                    console.log("用法: soloforge config <resolve|explain|confirm|unset> [options]");
-                    console.log("");
-                    console.log("  resolve  解析配置字段优先级（只读，显示所有候选来源）");
-                    console.log("  explain  解释指定字段的来源和优先级（只读，中文输出）");
-                    console.log("  confirm  确认配置字段值（写入 config + evidence）");
-                    console.log("  unset    移除指定字段的确认配置和 evidence");
+                    userInfo("用法: soloforge config <resolve|explain|confirm|unset> [options]");
+                    userInfo("");
+                    userInfo("  resolve  解析配置字段优先级（只读，显示所有候选来源）");
+                    userInfo("  explain  解释指定字段的来源和优先级（只读，中文输出）");
+                    userInfo("  confirm  确认配置字段值（写入 config + evidence）");
+                    userInfo("  unset    移除指定字段的确认配置和 evidence");
             }
             break;
         }
         case "status":
             await cmdStatus();
             break;
+        case "cleanup":
+            await cmdCleanup();
+            break;
         default:
-            console.log(`SoloForge CLI
+            userInfo(`SoloForge CLI
 
 用法: soloforge <命令>
 
@@ -121,17 +155,27 @@ async function main() {
   validate            验证项目配置和知识文件（config.yaml 可选，缺失时自动推断）
   validate-mechanisms 验证双层机制承载模型完整性（模板层 + 机制层）
   audit-template-mechanisms 扫描模板与机制注册表交叉校验（--json 输出完整报告，--changed-only 仅检查变更文件）
+  audit-design-artifacts 审计架构/数据库/API 设计产物包（只读，--json 输出报告）
+  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 unset <field>  移除确认配置
   status                显示当前项目的 SoloForge 状态
+  cleanup               清理过期任务和 evidence（默认 dry-run，--apply 执行实际清理）
 `);
     }
 }
 async function cmdInitAuto() {
-    console.error("[soloForge] CLI: 执行 cmdInitAuto");
+    debug("CLI", "执行 cmdInitAuto");
     const dryRun = args.includes("--dry-run");
     const projectPathArg = getArgValue("--project-path");
     const projectPath = projectPathArg ? path.resolve(projectPathArg) : process.cwd();
@@ -142,50 +186,50 @@ async function cmdInitAuto() {
     // 层 3: 字段级 evidence
     const evidence = generateConfigEvidence(fp, draft, "auto");
     // 展示探测结果 + evidence
-    console.log("\nSoloForge 自动配置探测结果:");
-    console.log("=".repeat(50));
+    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);
-        console.log(`  ${icon} ${key}: ${valStr} (${field.confidence}, ${field.confidence_source})`);
-        console.log(`     证据: ${field.evidence.join(", ")}`);
+        userInfo(`  ${icon} ${key}: ${valStr} (${field.confidence}, ${field.confidence_source})`);
+        userInfo(`     证据: ${field.evidence.join(", ")}`);
     }
-    console.log("=".repeat(50));
-    console.log(`综合置信度: ${draft.confidence}`);
+    userInfo("=".repeat(50));
+    userInfo(`综合置信度: ${draft.confidence}`);
     if (draft.advisory_notes.length > 0) {
-        console.log("建议:");
+        userInfo("建议:");
         for (const note of draft.advisory_notes) {
-            console.log(`  - ${note}`);
+            userInfo(`  - ${note}`);
         }
     }
     // Schema 校验 (advisory)
     const validation = validateConfigDraft(draft);
     if (validation.warnings.length > 0) {
-        console.log("\nschema 建议:");
+        userInfo("\nschema 建议:");
         for (const w of validation.warnings) {
-            console.log(`  ⚠️ ${w}`);
+            userInfo(`  ⚠️ ${w}`);
         }
     }
     if (!validation.valid) {
-        console.log("\nschema 错误:");
+        userInfo("\nschema 错误:");
         for (const e of validation.errors) {
-            console.log(`  ❌ ${e}`);
+            userInfo(`  ❌ ${e}`);
         }
-        console.log("\n配置校验失败，请手动运行 `soloforge init --interactive`。");
+        userInfo("\n配置校验失败，请手动运行 `soloforge init --interactive`。");
         return;
     }
     if (dryRun) {
-        console.log("\n[dry-run] 不写入文件。使用不带 --dry-run 的命令执行写入。");
+        userInfo("\n[dry-run] 不写入文件。使用不带 --dry-run 的命令执行写入。");
         return;
     }
     // 写入门禁: 所有必要字段必须 high confidence + detected/user_declared/confirmed
     const gate = canAutoWrite(evidence);
     if (!gate.allowed) {
-        console.log(`\n⚠️ 存在低/中置信度配置项，拒绝写入:`);
+        userInfo(`\n⚠️ 存在低/中置信度配置项，拒绝写入:`);
         for (const f of gate.blockedFields) {
-            console.log(`  - ${f}`);
+            userInfo(`  - ${f}`);
         }
-        console.log("请使用 `soloforge init --interactive` 或 `soloforge init --blueprint \"...\"` 生成配置。");
+        userInfo("请使用 `soloforge init --interactive` 或 `soloforge init --blueprint \"...\"` 生成配置。");
         return;
     }
     // 写入配置 + evidence
@@ -245,9 +289,9 @@ function writeConfigWithEvidence(projectPath, draft, evidence) {
         fss.writeFileSync(evidencePath, JSON.stringify(existing, null, 2), "utf-8");
     }
     catch (e) {
-        console.error(`[soloForge] 更新 evidence 文件失败: ${e instanceof Error ? e.message : String(e)}`);
+        internalWarn("CLI", `更新 evidence 文件失败: ${e instanceof Error ? e.message : String(e)}`);
     }
-    console.log(`\n✅ .soloforge/config.yaml + config.evidence.json created`);
+    userInfo(`\n✅ .soloforge/config.yaml + config.evidence.json created`);
 }
 function hashConfigValue(str) {
     return crypto.createHash("sha256").update(str).digest("hex").slice(0, 16);
@@ -261,18 +305,18 @@ function mapLegacySource(source) {
     }
 }
 async function cmdInitBlueprint() {
-    console.error("[soloForge] CLI: 执行 cmdInitBlueprint");
+    debug("CLI", "执行 cmdInitBlueprint");
     const blueprintText = getArgValue("--blueprint");
     if (!blueprintText) {
-        console.error("❌ --blueprint 需要提供描述文本，例如: soloforge init --blueprint \"Spring Boot + React 的 B2B 内部管理系统\"");
+        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) {
-        console.log("⚠️ 无法从蓝图文本解析技术栈，请使用 --interactive。");
-        console.log("支持的框架关键词: Spring Boot, Go, Rust, Gradle, React, Vue, Angular, Next.js, Nuxt");
+        userInfo("⚠️ 无法从蓝图文本解析技术栈，请使用 --interactive。");
+        userInfo("支持的框架关键词: Spring Boot, Go, Rust, Gradle, React, Vue, Angular, Next.js, Nuxt");
         return;
     }
     // 从解析的蓝图构建草稿
@@ -335,7 +379,7 @@ function blueprintFrontendCommands(framework) {
     }
 }
 async function cmdInit() {
-    console.error("[soloForge] CLI: 执行 cmdInit");
+    debug("CLI", "执行 cmdInit");
     const interactive = args.includes("--interactive");
     const adapter = getArgValue("--adapter") || "claude-code";
     const projectPathArg = getArgValue("--project-path");
@@ -368,7 +412,7 @@ async function cmdInit() {
             writeConfigWithEvidence(projectPath, config.draft, config.evidence);
         }
         else if (!process.stdin.isTTY) {
-            console.log("⚠️ interactive requires TTY. 请使用 --auto 或 --blueprint。");
+            userInfo("⚠️ interactive requires TTY. 请使用 --auto 或 --blueprint。");
         }
     }
     // 生成 .mcp.json（SoloForge + Playwright）
@@ -389,7 +433,7 @@ async function cmdInit() {
                 },
             };
             fss.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2), "utf-8");
-            console.log("✅ .mcp.json 已创建（soloforge + playwright）");
+            userInfo("✅ .mcp.json 已创建（soloforge + playwright）");
         }
         // 生成 hooks
         await cmdGenerateHooks(projectPath);
@@ -399,7 +443,7 @@ async function cmdInit() {
     // 生成 Trae IDE 配置
     if (adapter === "trae" || adapter === "all") {
         await cmdGenerateTraeInner(projectPath);
-        console.log("💡 提示: 使用项目级 .trae/ 配置需在 Trae 中开启 beta flag");
+        userInfo("💡 提示: 使用项目级 .trae/ 配置需在 Trae 中开启 beta flag");
     }
     // 生成 Codex App 配置
     if (adapter === "codex" || adapter === "all") {
@@ -410,7 +454,7 @@ async function cmdInit() {
     await copyKnowledgeTemplates(projectPath);
     // 确保 .gitignore 包含必要条目
     ensureGitignore(projectPath);
-    console.log(`\n✅ SoloForge 初始化完成 (适配器: ${adapter})。${adapter === "trae" ? "请打开 Trae IDE 开始使用。" :
+    userInfo(`\n✅ SoloForge 初始化完成 (适配器: ${adapter})。${adapter === "trae" ? "请打开 Trae IDE 开始使用。" :
         adapter === "codex" ? "请打开 Codex App 开始使用。" :
             adapter === "all" ? "可在 Claude Code、Trae IDE 或 Codex App 中使用。" :
                 "请打开 Claude Code 开始使用。"}`);
@@ -421,14 +465,25 @@ async function copyGlobalPatterns(projectPath) {
     const templatesDir = path.resolve(import.meta.dirname, "..", "..", "templates", "patterns");
     if (fss.existsSync(templatesDir)) {
         const files = fss.readdirSync(templatesDir).filter((f) => f.endsWith(".md"));
+        let copiedCount = 0;
+        let skippedCount = 0;
         for (const f of files) {
             const src = path.join(templatesDir, f);
             const dest = path.join(globalDir, f);
             if (!fss.existsSync(dest)) {
                 fss.copyFileSync(src, dest);
+                copiedCount++;
+            }
+            else {
+                skippedCount++;
             }
         }
-        console.log(`✅ ${files.length} 个默认模板已复制到 ~/.soloforge/patterns/`);
+        const parts = [];
+        if (copiedCount > 0)
+            parts.push(`新增 ${copiedCount} 个`);
+        if (skippedCount > 0)
+            parts.push(`跳过 ${skippedCount} 个（已存在）`);
+        userInfo(`✅ 全局模板 ~/.soloforge/patterns/: ${parts.length > 0 ? parts.join("，") : `${files.length} 个（已全部存在）`}`);
     }
 }
 async function copyKnowledgeTemplates(projectPath) {
@@ -453,7 +508,7 @@ async function copyKnowledgeTemplates(projectPath) {
             }
         }
         if (copiedCount > 0) {
-            console.log(`✅ ${copiedCount} 个知识模板已复制到 .soloforge/knowledge/`);
+            userInfo(`✅ ${copiedCount} 个知识模板已复制到 .soloforge/knowledge/`);
         }
     }
 }
@@ -468,7 +523,7 @@ async function generateAdapterConfigs(projectPath, adapter) {
                 },
             };
             fss.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2), "utf-8");
-            console.log("✅ .mcp.json 已创建（soloforge + playwright）");
+            userInfo("✅ .mcp.json 已创建（soloforge + playwright）");
         }
         await cmdGenerateHooks(projectPath);
         await cmdGenerateClaudeMdInner(projectPath);
@@ -486,7 +541,7 @@ function ensureGitignore(projectPath) {
     if (missing.length > 0) {
         const addition = (content.endsWith("\n") ? "" : "\n") + missing.join("\n") + "\n";
         fss.appendFileSync(gitignorePath, addition, "utf-8");
-        console.log(`✅ .gitignore 已更新: ${missing.join(", ")}`);
+        userInfo(`✅ .gitignore 已更新: ${missing.join(", ")}`);
     }
 }
 async function cmdGenerateHooks(projectPath) {
@@ -507,7 +562,7 @@ async function cmdGenerateHooks(projectPath) {
     // 仅 merge hooks 字段，保留用户的 permissions/env 等设置
     existing.hooks = hooksConfig.hooks;
     fss.writeFileSync(settingsPath, JSON.stringify(existing, null, 2), "utf-8");
-    console.log("✅ .claude/settings.json 已更新 hooks 配置");
+    userInfo("✅ .claude/settings.json 已更新 hooks 配置");
 }
 async function cmdGenerateClaudeMd() {
     await cmdGenerateClaudeMdInner(process.cwd());
@@ -524,16 +579,16 @@ async function cmdGenerateCodexInner(projectPath) {
     fss.mkdirSync(codexDir, { recursive: true });
     const tomlContent = generateCodexMcpConfig(projectPath);
     fss.writeFileSync(path.join(codexDir, "config.toml"), tomlContent, "utf-8");
-    console.log("✅ .codex/config.toml 已创建");
+    userInfo("✅ .codex/config.toml 已创建");
     // 生成 .codex/hooks.json
     const hooksContent = generateCodexHooksConfig();
     fss.writeFileSync(path.join(codexDir, "hooks.json"), hooksContent, "utf-8");
-    console.log("✅ .codex/hooks.json 已创建");
+    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");
-    console.log("✅ AGENTS.md 已创建");
+    userInfo("✅ AGENTS.md 已创建");
 }
 async function cmdGenerateTraeInner(projectPath) {
     // 生成 .trae/mcp.json
@@ -542,20 +597,20 @@ async function cmdGenerateTraeInner(projectPath) {
     const traeMcpPath = path.join(traeDir, "mcp.json");
     const traeMcpConfig = generateTraeMcpConfig(projectPath);
     fss.writeFileSync(traeMcpPath, JSON.stringify(traeMcpConfig, null, 2), "utf-8");
-    console.log("✅ .trae/mcp.json created");
+    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");
-    console.log("✅ .trae/rules/project_rules.md created");
+    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");
-    console.log("✅ CLAUDE.md created");
+    userInfo("✅ CLAUDE.md created");
 }
 async function cmdCheckWrite() {
     debugLog("CLI: 执行 cmdCheckWrite");
@@ -591,16 +646,24 @@ async function cmdCheckWrite() {
         }
         // 加载配置
         const projectPath = resolveProjectPath();
-        const { config } = await resolveProjectConfig(projectPath);
+        const { config, source } = await resolveProjectConfig(projectPath);
         // 从配置中收集所有允许路径
-        const allowedPaths = [
+        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 result = checkScope(filePath, allowedPaths, content || undefined);
+        const rawTargetFilePath = path.isAbsolute(filePath) ? filePath : path.resolve(projectPath, filePath);
+        const projectRealPath = fss.realpathSync(projectPath);
+        const targetFilePath = rawTargetFilePath === projectPath || rawTargetFilePath.startsWith(projectPath + path.sep)
+            ? path.join(projectRealPath, path.relative(projectPath, rawTargetFilePath))
+            : rawTargetFilePath;
+        const result = checkScope(targetFilePath, allowedPaths, content || undefined);
         // 隐私/秘密契约：禁止读取的模式 
         if (isReadForbidden(filePath)) {
             process.stdout.write(JSON.stringify({
@@ -624,12 +687,37 @@ async function cmdCheckWrite() {
             process.exit(0);
         }
         if (result.severity === "warning") {
-            console.error(JSON.stringify(result));
+            jsonSafeError(JSON.stringify(result));
+        }
+        // 问题六十二: Claude Code 直接 Edit/Write 也必须遵守设计产物就绪门。
+        // 设计资产本身允许继续修订；非设计文件在产物包复验通过前禁止写入。
+        const relativeFilePath = path.relative(projectRealPath, targetFilePath).replaceAll(path.sep, "/");
+        const isDesignArtifactFile = /^docs\/architecture\//.test(relativeFilePath) ||
+            /^docs\/api\/openapi\.(?:ya?ml|json)$/.test(relativeFilePath) ||
+            /^db\/(?:migrations|schema)\//.test(relativeFilePath);
+        if (!isDesignArtifactFile) {
+            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 currentTask = await manager.getCurrentTask();
+                const designPack = currentTask?.design_artifact_pack;
+                if (designPack && designPack.status !== "implementation_ready") {
+                    process.stdout.write(JSON.stringify({
+                        hookSpecificOutput: {
+                            hookEventName: "PreToolUse",
+                            permissionDecision: "deny",
+                            permissionDecisionReason: `设计产物包状态为 ${designPack.status}，请先完善 docs/architecture、docs/api/openapi 或 db/migrations|schema 并通过复验，再写入业务实现`,
+                        },
+                    }));
+                    process.exit(0);
+                }
+            }
         }
         process.exit(0); // 允许
     }
     catch (e) {
-        console.error(`SoloForge 写入检查错误: ${e instanceof Error ? e.message : String(e)}`);
+        userError(`SoloForge 写入检查错误: ${e instanceof Error ? e.message : String(e)}`);
         process.exit(1);
     }
 }
@@ -639,16 +727,20 @@ function resolveProjectPath() {
         try {
             const stat = fss.statSync(envPath);
             if (!stat.isDirectory()) {
-                console.error(`⚠️  SOLOFORGE_PROJECT (${envPath}) 不是目录，回退到 cwd`);
+                userWarn(`⚠️  SOLOFORGE_PROJECT (${envPath}) 不是目录，回退到 cwd`);
                 return process.cwd();
             }
             return envPath;
         }
         catch {
-            console.error(`⚠️  SOLOFORGE_PROJECT (${envPath}) 路径不存在，回退到 cwd`);
+            userWarn(`⚠️  SOLOFORGE_PROJECT (${envPath}) 路径不存在，回退到 cwd`);
             return process.cwd();
         }
     }
+    const projectPathArg = getArgValue("--project-path");
+    if (projectPathArg) {
+        return path.resolve(projectPathArg);
+    }
     return process.cwd();
 }
 async function cmdPostBash() {
@@ -699,12 +791,12 @@ async function cmdPrePrompt() {
         }
     }
     catch (e) {
-        console.error("[soloForge] pre-prompt hook 错误:", e);
+        internalWarn("CLI", "pre-prompt hook 错误:", e);
     }
     process.exit(0);
 }
 async function checkEvidenceWarnings(projectPath) {
-    console.error("[soloForge] CLI: 执行 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");
@@ -773,16 +865,16 @@ function getConfigFieldValue(config, key) {
     return obj;
 }
 async function cmdValidate() {
-    console.error("[soloForge] CLI: 执行 cmdValidate");
-    const projectPath = process.cwd();
+    debug("CLI", "执行 cmdValidate");
+    const projectPath = resolveProjectPath();
     try {
         const { config, source } = await resolveProjectConfig(projectPath);
         if (source === "inferred") {
-            console.log("ℹ️  未找到 .soloforge/config.yaml — 使用自动推断的配置。");
-            console.log("   运行 'soloforge init --auto' 可持久化。");
+            userInfo("ℹ️  未找到 .soloforge/config.yaml — 使用自动推断的配置。");
+            userInfo("   运行 'soloforge init --auto' 可持久化。");
         }
         else {
-            console.log("✅ config.yaml 有效");
+            userInfo("✅ config.yaml 有效");
         }
         // 使用共享函数验证配置优先级
         let hasHardFail = false;
@@ -793,43 +885,122 @@ async function cmdValidate() {
             const advisory = findings.filter(f => f.severity === "advisory");
             if (hardFails.length > 0) {
                 hasHardFail = true;
-                console.log(`❌ 配置优先级: ${hardFails.length} hard_fail`);
+                userInfo(`❌ 配置优先级: ${hardFails.length} hard_fail`);
                 for (const f of hardFails) {
-                    console.log(`  - [${f.rule}] ${f.field_path ?? "N/A"}: ${f.message}`);
+                    userInfo(`  - [${f.rule}] ${f.field_path ?? "N/A"}: ${f.message}`);
                 }
             }
             if (advisory.length > 0) {
-                console.log(`⚠️  配置优先级: ${advisory.length} advisory`);
+                userInfo(`⚠️  配置优先级: ${advisory.length} advisory`);
                 for (const f of advisory) {
-                    console.log(`  - [${f.rule}] ${f.field_path ?? "N/A"}: ${f.message}`);
+                    userInfo(`  - [${f.rule}] ${f.field_path ?? "N/A"}: ${f.message}`);
                 }
             }
             if (hardFails.length === 0 && advisory.length === 0) {
-                console.log("✅ 配置优先级验证通过");
+                userInfo("✅ 配置优先级验证通过");
             }
         }
         catch { }
         // Evidence 检查
         const evidenceWarnings = await checkEvidenceWarnings(projectPath);
         for (const w of evidenceWarnings) {
-            console.log(`⚠️  evidence: ${w}`);
+            userInfo(`⚠️  evidence: ${w}`);
         }
         // 检查知识文件
         const knowledgeDir = getProjectKnowledgeDir(config);
         if (fss.existsSync(knowledgeDir)) {
             const { KnowledgeIndexManager } = await import("../knowledge/index_manager.js");
-            const index = new KnowledgeIndexManager(config);
-            await index.build();
-            const entries = index.getAllEntries();
-            console.log(`✅ ${entries.project.length} 条项目知识已索引`);
-            const issues = await index.checkHealth();
-            if (issues.length > 0) {
-                console.log(`⚠️  ${issues.length} 个健康问题:`);
-                for (const { entry, issue } of issues) {
-                    console.log(`  - ${entry.name}: ${issue}`);
+            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();
+            }
+        }
+        // 扩展清单校验 (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;
+            }
+            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;
+            }
+            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;
+                }
+                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");
@@ -837,29 +1008,78 @@ async function cmdValidate() {
             const dlHard = dlFindings.filter((f) => f.severity === "hard_fail");
             const dlAdvisory = dlFindings.filter((f) => f.severity === "advisory");
             if (dlHard.length > 0) {
-                console.log(`❌ 双层机制验证: ${dlHard.length} hard_fail`);
+                userInfo(`❌ 双层机制验证: ${dlHard.length} hard_fail`);
                 for (const f of dlHard) {
-                    console.log(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
+                    userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
                 }
-                console.error(`❌ validate 失败: 双层机制存在 ${dlHard.length} hard_fail`);
+                userError(`❌ validate 失败: 双层机制存在 ${dlHard.length} hard_fail`);
                 process.exit(1);
             }
             else {
-                console.log(`✅ 双层机制验证: ${dlAdvisory.length} advisory, 0 hard_fail`);
+                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;
+                }
+                else {
+                    userInfo(`✅ 测试策略覆盖: 已检查 ${tsChecked} 个 enforced 契约`);
+                }
+            }
+            catch (e) {
+                userError(`❌ 测试策略验证异常: ${e.message}`);
+                hasHardFail = true;
             }
         } // 双层机制检查结束
         if (hasHardFail) {
-            console.error("❌ validate 失败: 配置优先级存在 hard_fail");
+            userError("❌ validate 失败: 配置优先级存在 hard_fail");
             process.exit(1);
         }
     }
     catch (e) {
-        console.error(`❌ 验证失败: ${e.message}`);
+        userError(`❌ 验证失败: ${e.message}`);
         process.exit(1);
     }
 }
 async function cmdValidateMechanisms() {
-    console.error("[soloForge] CLI: 执行 cmdValidateMechanisms");
+    debug("CLI", "执行 cmdValidateMechanisms");
     // 从编译后的二进制位置推导根目录: dist/bin/soloforge.js -> 项目根
     const soloforgeRoot = path.resolve(import.meta.dirname, "..", "..");
     const projectPath = fss.existsSync(path.join(soloforgeRoot, "src", "engine"))
@@ -871,47 +1091,68 @@ async function cmdValidateMechanisms() {
         const hardFails = findings.filter((f) => f.severity === "hard_fail");
         const advisory = findings.filter((f) => f.severity === "advisory");
         if (findings.length === 0) {
-            console.log("✅ 所有双层机制映射验证通过，无发现。");
+            userInfo("✅ 所有双层机制映射验证通过，无发现。");
             process.exit(0);
             return;
         }
         if (advisory.length > 0) {
-            console.log(`⚠️  advisory findings (${advisory.length}):`);
+            userInfo(`⚠️  advisory findings (${advisory.length}):`);
             for (const f of advisory) {
-                console.log(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
+                userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
             }
         }
         if (hardFails.length > 0) {
-            console.log(`❌ hard_fail findings (${hardFails.length}):`);
+            userInfo(`❌ hard_fail findings (${hardFails.length}):`);
             for (const f of hardFails) {
-                console.log(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
+                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`);
             }
-            console.log(`\n❌ 双层机制验证失败: ${hardFails.length} hard_fail`);
+        }
+        catch (e) {
+            userError(`❌ 机制族验证异常: ${e.message}`);
             process.exit(1);
         }
-        console.log(`\n✅ 双层机制验证通过，${advisory.length} advisory findings`);
         // 审计摘要
         try {
             const { auditTemplateMechanisms } = await import("../engine/template_mechanism_auditor.js");
             const audit = auditTemplateMechanisms(projectPath);
             if (audit.hard_fail_count > 0) {
-                console.log(`\n⚠️  模板审计摘要: ${audit.hard_fail_count} hard_fail, ${audit.unmapped_template_assets.length} unmapped`);
+                userInfo(`\n❌ 模板审计摘要: ${audit.hard_fail_count} hard_fail, ${audit.unmapped_template_assets.length} unmapped`);
+                process.exit(1);
             }
             else {
-                console.log(`\n📊 模板审计: ${audit.total_template_files} 文件, ${audit.unmapped_template_assets.length} unmapped, ${audit.advisory_count} advisory`);
+                userInfo(`\n📊 模板审计: ${audit.total_template_files} 文件, ${audit.unmapped_template_assets.length} unmapped, ${audit.advisory_count} advisory`);
             }
         }
-        catch {
-            // 审计仅为建议，不阻断
+        catch (e) {
+            userError(`❌ 模板审计异常: ${e.message}`);
+            process.exit(1);
         }
     }
     catch (e) {
-        console.error(`❌ validate-mechanisms 失败: ${e.message}`);
+        userError(`❌ validate-mechanisms 失败: ${e.message}`);
         process.exit(1);
     }
 }
 async function cmdAuditTemplateMechanisms() {
-    console.error("[soloForge] CLI: 执行 cmdAuditTemplateMechanisms");
+    debug("CLI", "执行 cmdAuditTemplateMechanisms");
     const asJson = args.includes("--json");
     const changedOnly = args.includes("--changed-only");
     // 从编译后的二进制位置推导根目录
@@ -923,108 +1164,718 @@ async function cmdAuditTemplateMechanisms() {
         const { auditTemplateMechanisms } = await import("../engine/template_mechanism_auditor.js");
         const report = auditTemplateMechanisms(projectPath);
         if (asJson) {
-            console.log(JSON.stringify(report, null, 2));
+            userInfo(JSON.stringify(report, null, 2));
             if (report.hard_fail_count > 0) {
                 process.exit(1);
             }
             return;
         }
         // 人类可读输出
-        console.log(`模板-机制审计报告 (${report.generated_at})`);
-        console.log(`  模板文件: ${report.total_template_files}`);
-        console.log(`  注册资产: ${report.total_registered_assets}`);
-        console.log(`  机制总数: ${report.total_mechanisms}`);
-        console.log("");
+        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) {
-            console.log(`⚠️  未注册模板 (${report.unmapped_template_assets.length}):`);
+            userInfo(`⚠️  未注册模板 (${report.unmapped_template_assets.length}):`);
             for (const u of report.unmapped_template_assets) {
-                console.log(`  - ${u.path}`);
+                userInfo(`  - ${u.path}`);
             }
         }
         if (report.unconsumed_template_assets.length > 0) {
-            console.log(`⚠️  未消费资产 (${report.unconsumed_template_assets.length}):`);
+            userInfo(`⚠️  未消费资产 (${report.unconsumed_template_assets.length}):`);
             for (const u of report.unconsumed_template_assets) {
-                console.log(`  - ${u.path} (mode=${u.consumption_mode})`);
+                userInfo(`  - ${u.path} (mode=${u.consumption_mode})`);
             }
         }
         if (report.code_only_mechanisms.length > 0) {
-            console.log(`⚠️  仅代码机制 (无模板层):`);
+            userInfo(`⚠️  仅代码机制 (无模板层):`);
             for (const m of report.code_only_mechanisms) {
-                console.log(`  - ${m.mechanism_id} (${m.priority}, ${m.status})`);
+                userInfo(`  - ${m.mechanism_id} (${m.priority}, ${m.status})`);
             }
         }
         if (report.template_only_mechanisms.length > 0) {
-            console.log(`⚠️  仅模板机制 (无代码层):`);
+            userInfo(`⚠️  仅模板机制 (无代码层):`);
             for (const m of report.template_only_mechanisms) {
-                console.log(`  - ${m.mechanism_id} (${m.priority}, ${m.status})`);
+                userInfo(`  - ${m.mechanism_id} (${m.priority}, ${m.status})`);
             }
         }
         if (report.required_assets_without_enforcer.length > 0) {
-            console.log(`❌ Required 资产无 enforcer (${report.required_assets_without_enforcer.length}):`);
+            userInfo(`❌ Required 资产无 enforcer (${report.required_assets_without_enforcer.length}):`);
             for (const r of report.required_assets_without_enforcer) {
-                console.log(`  - ${r.path} (mechanism=${r.owner_mechanism_id})`);
+                userInfo(`  - ${r.path} (mechanism=${r.owner_mechanism_id})`);
             }
         }
         if (report.overpromised_adapter_rules.length > 0) {
-            console.log(`❌ 适配器过度承诺 (${report.overpromised_adapter_rules.length}):`);
+            userInfo(`❌ 适配器过度承诺 (${report.overpromised_adapter_rules.length}):`);
             for (const o of report.overpromised_adapter_rules) {
-                console.log(`  - ${o.source_file}: ${o.promised_mechanism_id} (${o.promise_keywords.join(",")})`);
+                userInfo(`  - ${o.source_file}: ${o.promised_mechanism_id} (${o.promise_keywords.join(",")})`);
             }
         }
         if (report.deprecated_assets_injected.length > 0) {
-            console.log(`⚠️  Deprecated 资产仍被注入:`);
+            userInfo(`⚠️  Deprecated 资产仍被注入:`);
             for (const d of report.deprecated_assets_injected) {
-                console.log(`  - ${d.path}`);
+                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) {
-                console.log(`⚠️  漂移 advisory (${driftAdvisory.length}):`);
+                userInfo(`⚠️  漂移 advisory (${driftAdvisory.length}):`);
                 for (const f of driftAdvisory) {
-                    console.log(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
+                    userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
                 }
             }
             if (driftHard.length > 0) {
-                console.log(`❌ 漂移 hard_fail (${driftHard.length}):`);
+                userInfo(`❌ 漂移 hard_fail (${driftHard.length}):`);
                 for (const f of driftHard) {
-                    console.log(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
+                    userInfo(`  - [${f.finding_type}] ${f.mechanism_id}: ${f.message}`);
                 }
             }
         }
-        console.log("");
+        userInfo("");
         if (report.hard_fail_count > 0) {
-            console.log(`❌ 审计失败: ${report.hard_fail_count} hard_fail, ${report.advisory_count} advisory`);
-            process.exit(1);
+            userInfo(`❌ 审计失败: ${report.hard_fail_count} hard_fail, ${report.advisory_count} advisory`);
         }
         else {
-            console.log(`✅ 审计通过: 0 hard_fail, ${report.advisory_count} advisory`);
+            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) {
-        console.error(`❌ audit-template-mechanisms 失败: ${e.message}`);
+        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 (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");
+    // 读取当前包版本
+    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);
+    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 应用同步");
+    }
+    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 cmdValidateBatch1() {
-    console.error("[soloForge] CLI: 执行 cmdValidateBatch1");
+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 { validateBatch1Scenarios, validateBatch1ProblemMatrix } = await import("../engine/batch1_scenario_registry.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 validateBatch1Scenarios(mechanismsPass, auditPass, true);
+    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 = validateBatch1ProblemMatrix(cwd);
+        const problemMatrix = validateFoundationProblemMatrix(cwd);
         const problemAllPass = problemMatrix.every((p) => Object.values(p.dimensions).every((d) => d.status === "PASS"));
-        console.log(JSON.stringify({
+        userInfo(JSON.stringify({
             mechanisms_pass: mechanismsPass,
             audit_pass: auditPass,
             all_pass: allPass && problemAllPass,
@@ -1036,71 +1887,173 @@ async function cmdValidateBatch1() {
     else {
         for (const s of scenarioResults) {
             const icon = s.status === "PASS" ? "✓" : "✗";
-            console.log(`${icon} ${s.scenario_id}: ${s.scenario_name} — ${s.status}`);
+            userInfo(`${icon} ${s.scenario_id}: ${s.scenario_name} — ${s.status}`);
             for (const r of s.rules) {
                 const ri = r.status === "PASS" ? "  ✓" : "  ✗";
-                console.log(`${ri} ${r.rule}: ${r.evidence}`);
+                userInfo(`${ri} ${r.rule}: ${r.evidence}`);
             }
         }
-        console.log(allPass ? "\n所有场景通过" : "\n部分场景失败");
+        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 前缀匹配: "问题四十一" 匹配 "问题四十一(Brainstorm)"
+        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() {
-    console.error("[soloForge] CLI: 执行 cmdStatus");
-    const projectPath = process.cwd();
-    console.log(`SoloForge 状态: ${projectPath}`);
+    debug("CLI", "执行 cmdStatus");
+    const projectPath = resolveProjectPath();
+    userInfo(`SoloForge 状态: ${projectPath}`);
     const { config, source } = await resolveProjectConfig(projectPath);
-    console.log(`  配置来源: ${source === "config_file" ? "config.yaml" : "自动推断"}`);
-    console.log(`  产品: ${config.product_profile}`);
-    console.log(`  后端: ${config.tech_stack.backend.framework || "未配置"}`);
-    console.log(`  前端: ${config.tech_stack.frontend.framework || "未配置"}`);
+    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) {
-            console.log("");
-            console.log("  字段解析状态:");
+            userInfo("");
+            userInfo("  字段解析状态:");
             for (const r of resolutions) {
                 const stale = r.stale_warning ? " ⚠️ stale" : "";
                 const conflict = r.conflict_report ? " ⚠️ conflict" : "";
-                console.log(`    ${r.field_path}: ${JSON.stringify(r.resolved_value)} (${r.source}${stale}${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"));
-                console.log(`  evidence: schema_version=${raw.schema_version ?? 1}, ${entries.length} 条`);
+                userInfo(`  evidence: schema_version=${raw.schema_version ?? 1}, ${entries.length} 条`);
             }
             catch {
-                console.log("  evidence: 无法解析");
+                userInfo("  evidence: 无法解析");
             }
         }
         else if (source === "config_file") {
-            console.log("  evidence: ⚠️ config.evidence.json 缺失");
+            userInfo("  evidence: ⚠️ config.evidence.json 缺失");
         }
     }
     catch { }
     // Evidence 警告
     const evidenceWarnings = await checkEvidenceWarnings(projectPath);
     for (const w of evidenceWarnings) {
-        console.log(`  ⚠️  evidence: ${w}`);
+        userInfo(`  ⚠️  evidence: ${w}`);
     }
     const knowledgeDir = getProjectKnowledgeDir(config);
     if (fss.existsSync(knowledgeDir)) {
         const { KnowledgeIndexManager } = await import("../knowledge/index_manager.js");
-        const index = new KnowledgeIndexManager(config);
-        await index.build();
-        const entries = index.getAllEntries();
-        console.log(`  知识: ${entries.global.length} 全局 + ${entries.project.length} 项目`);
+        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 {
-        console.log("  知识: 未初始化");
+        userInfo("  知识: 未初始化");
     }
 }
 async function interactiveConfig(projectPath) {
-    console.error("[soloForge] CLI: 执行 interactiveConfig");
+    debug("CLI", "执行 interactiveConfig");
     if (!process.stdin.isTTY)
         return undefined;
     const readline = await import("node:readline");
@@ -1146,22 +2099,165 @@ async function interactiveConfig(projectPath) {
     return { draft, evidence };
 }
 function cmdVersion() {
-    console.error("[soloForge] CLI: 执行 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"));
-        console.log("SoloForge v" + pkg.version);
+        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"));
-        console.log("SoloForge v" + pkg.version);
+        userInfo("SoloForge v" + pkg.version);
     }
 }
-main().catch((e) => { console.error(e); process.exit(1); });
+async function cmdCleanup() {
+    debug("CLI", "执行 cmdCleanup");
+    const dryRun = !args.includes("--apply");
+    const projectPath = process.cwd();
+    const stateDir = path.join(projectPath, ".soloforge", "state");
+    let hasError = false;
+    userInfo(`SoloForge 清理: ${projectPath}`);
+    userInfo(`  模式: ${dryRun ? "dry-run（仅评估）" : "⚠️ 实际清理"}`);
+    // 收集所有 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;