soloforge 1.3.0 → 1.3.2

package/dist/adapters/shared/workflow_template.js

@@ -1,55 +1,154 @@
 import { debug } from "../../engine/logger.js";
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { findLayerMapByMechanismId } from "../../engine/dual_layer_mechanism_registry.js";
+import { WORKFLOW_TEMPLATE_HARD_RULES } from "../../engine/asset_manifest.js";
+const SF_HARD_RULE_RE = /@sf-hard-rule[^>]*mechanism=(\S+)/g;
+/** 从结构化清单生成 @sf-hard-rule 标记 */
+function hardRuleTag(ruleId) {
+    const rule = WORKFLOW_TEMPLATE_HARD_RULES.find(r => r.rule_id === ruleId);
+    if (!rule)
+        return `<!-- @sf-hard-rule id=${ruleId} MISSING_IN_MANIFEST -->`;
+    return `<!-- @sf-hard-rule id=${rule.rule_id} mechanism=${rule.mechanism_id} enforcement=${rule.enforcement_status} summary="${rule.rule_summary}" -->`;
+}
+/** 渲染一条规则的 marker + user_instruction */
+function renderRule(ruleId) {
+    const rule = WORKFLOW_TEMPLATE_HARD_RULES.find(r => r.rule_id === ruleId);
+    const tag = hardRuleTag(ruleId);
+    const text = rule?.user_instruction ?? "";
+    if (text)
+        return `${tag}\n${text}`;
+    return tag;
+}
+/** 渲染一组规则（marker + user_instruction） */
+function renderRules(ruleIds) {
+    return ruleIds.map(id => renderRule(id)).join("\n");
+}
+/** 工作流步骤定义: 每步包含标题和有序规则 ID */
+const WORKFLOW_STEPS = [
+    { title: "", rule_ids: ["wf-privacy-before-expand", "wf-knowledge-injection", "wf-core-principles"] },
+    { title: "### 步骤 1: 分类", rule_ids: ["wf-classify-first"] },
+    { title: "### 步骤 1.5: 入口裁决", rule_ids: ["wf-routing-gate", "wf-strategy-no-route"] },
+    { title: "### 步骤 1.6: 多阶段拆解", rule_ids: ["wf-multi-stage-loop"] },
+    { title: "### 步骤 2: 执行", rule_ids: ["wf-dispatch-by-route", "wf-command-contract", "wf-tool-contract", "wf-architecture-workshop-first", "wf-design-artifact-pack", "wf-standard-asset-contract", "wf-template-asset-visibility"] },
+    { title: "### 步骤 3: 验证", rule_ids: ["wf-verify-after-change", "wf-evidence-grounding"] },
+    { title: "### 步骤 4: 学习", rule_ids: ["wf-learn-after-verify"] },
+    { title: "### 步骤 5: 汇报", rule_ids: ["wf-no-auto-capability-change"] },
+];
+/**
+ * 计算所有权威规则资产的第一行非注释内容组合的 SHA256 校验和。
+ * 权威规则内容变化时校验和必然变化。
+ */
+export function computeAuthoritativeRulesChecksum(rootDir) {
+    const mechanismIds = getWorkflowRuleMechanismIds();
+    const parts = [];
+    for (const mid of mechanismIds) {
+        const map = findLayerMapByMechanismId(mid);
+        if (!map?.template_assets)
+            continue;
+        for (const asset of map.template_assets) {
+            const fullPath = path.join(rootDir, asset.path);
+            if (!fs.existsSync(fullPath))
+                continue;
+            const content = fs.readFileSync(fullPath, "utf-8");
+            // 取前 200 字符（去掉 frontmatter 后的首段）作为校验依据
+            const bodyStart = content.indexOf("---", content.indexOf("---") + 3);
+            const body = bodyStart >= 0 ? content.substring(bodyStart + 3).trimStart() : content;
+            parts.push(`${asset.path}:${body.substring(0, 500)}`);
+        }
+    }
+    return crypto.createHash("sha256").update(parts.join("\n")).digest("hex").substring(0, 16);
+}
+/**
+ * 提取 generateWorkflowRules 输出中所有 @sf-hard-rule 引用的机制 ID（去重）。
+ */
+export function getWorkflowRuleMechanismIds() {
+    const text = generateWorkflowRules({});
+    const ids = new Set();
+    let m;
+    while ((m = SF_HARD_RULE_RE.exec(text)) !== null) {
+        ids.add(m[1]);
+    }
+    return [...ids];
+}
+/**
+ * 校验工作流模板中每条 @sf-hard-rule 都能找到权威机制注册条目，
+ * 且其 template_layer 资产文件存在，且内容校验和与嵌入值一致。
+ */
+export function validateWorkflowRuleSources(rootDir) {
+    const mechanismIds = getWorkflowRuleMechanismIds();
+    const missing_mechanisms = [];
+    const missing_assets = [];
+    for (const mid of mechanismIds) {
+        const map = findLayerMapByMechanismId(mid);
+        if (!map) {
+            missing_mechanisms.push(mid);
+            continue;
+        }
+        if (map.template_assets) {
+            for (const asset of map.template_assets) {
+                if (!fs.existsSync(path.join(rootDir, asset.path))) {
+                    missing_assets.push(asset.path);
+                }
+            }
+        }
+    }
+    // 内容校验和验证
+    const computedChecksum = computeAuthoritativeRulesChecksum(rootDir);
+    const embeddedChecksum = getEmbeddedChecksum();
+    const checksumMismatch = computedChecksum !== embeddedChecksum;
+    return {
+        valid: missing_mechanisms.length === 0 && missing_assets.length === 0 && !checksumMismatch,
+        missing_mechanisms,
+        missing_assets,
+        checksum_mismatch: checksumMismatch,
+        embedded_checksum: embeddedChecksum,
+        computed_checksum: computedChecksum,
+    };
+}
+/** 当前嵌入的权威规则校验和 — 由 `npm run update-workflow-checksum` 更新。 */
+const EMBEDDED_CHECKSUM = "a875189c510913ff";
+function getEmbeddedChecksum() {
+    return EMBEDDED_CHECKSUM;
+}
+/**
+ * 更新嵌入校验和到源文件。由 CI 或开发者在确认权威规则变化后调用。
+ */
+export function updateEmbeddedChecksum(rootDir) {
+    const newChecksum = computeAuthoritativeRulesChecksum(rootDir);
+    const selfPath = path.join(rootDir, "src", "adapters", "shared", "workflow_template.ts");
+    if (fs.existsSync(selfPath)) {
+        let content = fs.readFileSync(selfPath, "utf-8");
+        content = content.replace(/const EMBEDDED_CHECKSUM = "[^"]*";/, `const EMBEDDED_CHECKSUM = "${newChecksum}";`);
+        fs.writeFileSync(selfPath, content, "utf-8");
+    }
+    return newChecksum;
+}
 /**
  * 生成工作流规则模板内容。
+ * 从 WORKFLOW_TEMPLATE_HARD_RULES 结构化清单循环渲染每条规则的 marker + user_instruction。
  * @param config - 项目配置
  * @returns 工作流规则文本
  */
 export function generateWorkflowRules(config) {
     debug("工作流模板", "生成工作流规则");
-    return `# SoloForge 集成规则
+    const header = `# SoloForge 集成规则
 
 ## 强制工作流
 
-当收到开发指令时（非纯对话/提问），必须按以下顺序执行:
-
-<!-- @sf-hard-rule id=wf-privacy-before-expand mechanism=mc-privacy-boundary enforcement=enforced -->
-<!-- @sf-hard-rule id=wf-knowledge-injection mechanism=mc-knowledge-injection-boundary enforcement=enforced -->
-<!-- @sf-hard-rule id=wf-core-principles mechanism=mc-core-engineering-principles enforcement=enforced -->
-### 步骤 1: 分类
-<!-- @sf-hard-rule id=wf-classify-first mechanism=mc-workflow-contract enforcement=enforced -->
-调用 \`sf_classify\` 分类。
-
-<!-- @sf-hard-rule id=wf-routing-gate mechanism=mc-workflow-contract enforcement=enforced -->
-### 步骤 1.5: 入口裁决
-按分类结果 \`route_decision\` 字段分发。详见知识库路由规则。
-
-<!-- @sf-hard-rule id=wf-strategy-no-route mechanism=mc-workflow-contract enforcement=enforced -->
-\`strategy\` 仅兼容展示，不作为入口裁决。
-
-<!-- @sf-hard-rule id=wf-multi-stage-loop mechanism=mc-workflow-contract enforcement=enforced -->
-### 步骤 1.6: 多阶段拆解
-\`execution_shape=multi_stage_plan\` 时: \`sf_plan\` → \`sf_expand\` → 执行 → \`sf_plan_advance\` → 循环。
-
-<!-- @sf-hard-rule id=wf-dispatch-by-route mechanism=mc-workflow-contract enforcement=enforced -->
-<!-- @sf-hard-rule id=wf-command-contract mechanism=mc-command-execution enforcement=enforced -->
-<!-- @sf-hard-rule id=wf-tool-contract mechanism=mc-tool-invocation-contract enforcement=enforced -->
-### 步骤 2: 执行
-按分类结果调用对应工具。详见知识库流程。
-
-<!-- @sf-hard-rule id=wf-verify-after-change mechanism=mc-verifier enforcement=enforced -->
-### 步骤 3: 验证
-代码修改后调用 \`sf_verify\` 并执行返回的验证命令。
-
-<!-- @sf-hard-rule id=wf-learn-after-verify mechanism=mc-task-context-lifecycle enforcement=enforced -->
-### 步骤 4: 学习
-验证后调用 \`sf_learn\`。若有 \`retry_hint\` 回到步骤 3。
-
-<!-- @sf-hard-rule id=wf-no-auto-capability-change mechanism=mc-guard-evaluation enforcement=enforced -->
-### 步骤 5: 汇报
-展示验证摘要和验收结果。
+当收到开发指令时（非纯对话/提问），必须按以下顺序执行:`;
+    const sections = WORKFLOW_STEPS.map(step => {
+        const rulesText = renderRules(step.rule_ids);
+        if (step.title)
+            return `${step.title}\n${rulesText}`;
+        return rulesText;
+    }).join("\n\n");
+    const footer = `## 项目信息
 
-## 项目信息
+项目事实以 config 配置及 tool 输出为准，不在模板中硬编码。
 
-项目事实以 config 配置及 tool 输出为准，不在模板中硬编码。`;
+<!-- @sf-checksum: ${EMBEDDED_CHECKSUM} -->`;
+    return `${header}\n\n${sections}\n\n${footer}`;
 }
 //# sourceMappingURL=workflow_template.js.map

package/dist/adapters/shared/workflow_template.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow_template.js","sourceRoot":"","sources":["../../../src/adapters/shared/workflow_template.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAC;AAE/C;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAC1B,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qCA4C4B,CAAC;AACtC,CAAC"}
+{"version":3,"file":"workflow_template.js","sourceRoot":"","sources":["../../../src/adapters/shared/workflow_template.ts"],"names":[],"mappings":"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"}

package/dist/bin/soloforge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"soloforge.d.ts","sourceRoot":"","sources":["../../src/bin/soloforge.ts"],"names":[],"mappings":";AAgxBA,OAAO,EAAE,0BAA0B,EAAE,MAAM,gDAAgD,CAAC"}
+{"version":3,"file":"soloforge.d.ts","sourceRoot":"","sources":["../../src/bin/soloforge.ts"],"names":[],"mappings":";AA6yBA,OAAO,EAAE,0BAA0B,EAAE,MAAM,gDAAgD,CAAC"}

package/dist/bin/soloforge.js

@@ -60,6 +60,12 @@ 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":
             userWarn("⚠️  validate-batch1 是历史施工命令，不代表正式发布通过。请使用 validate-release。");
             await cmdValidateFoundation();
@@ -75,6 +81,9 @@ async function main() {
         case "validate-release":
             await cmdValidateReleaseGate();
             break;
+        case "audit-template-visibility":
+            await cmdAuditTemplateVisibility();
+            break;
         case "sync-templates":
             await cmdSyncTemplates();
             break;
@@ -149,6 +158,8 @@ 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     [历史] 仅知识模板验证，不代表正式发布通过
@@ -452,45 +463,32 @@ async function cmdInit() {
                 "请打开 Claude Code 开始使用。"}`);
 }
 async function copyGlobalPatterns(projectPath) {
+    const { copyPatternsToGlobal } = await import("../engine/template_init_sync.js");
     const globalDir = getGlobalPatternsDir();
-    fss.mkdirSync(globalDir, { recursive: true });
-    const templatesDir = path.resolve(import.meta.dirname, "..", "..", "templates", "patterns");
-    if (fss.existsSync(templatesDir)) {
-        const files = fss.readdirSync(templatesDir).filter((f) => f.endsWith(".md"));
-        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);
-            }
-        }
-        userInfo(`✅ ${files.length} 个默认模板已复制到 ~/.soloforge/patterns/`);
+    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 knowledgeTemplatesDir = path.resolve(import.meta.dirname, "..", "..", "templates", "knowledge");
-    if (fss.existsSync(knowledgeTemplatesDir)) {
-        const subDirs = ["procedures", "domain", "product_profiles", "acceptance_templates", "review_rules", "patterns/core", "checklists", "templates"];
-        let copiedCount = 0;
-        for (const subDir of subDirs) {
-            const srcDir = path.join(knowledgeTemplatesDir, subDir);
-            if (!fss.existsSync(srcDir))
-                continue;
-            const destDir = path.join(projectPath, ".soloforge", "knowledge", subDir);
-            fss.mkdirSync(destDir, { recursive: true });
-            const files = fss.readdirSync(srcDir).filter((f) => f.endsWith(".md") || f.endsWith(".yaml") || f.endsWith(".yml"));
-            for (const f of files) {
-                const src = path.join(srcDir, f);
-                const dest = path.join(destDir, f);
-                if (!fss.existsSync(dest)) {
-                    fss.copyFileSync(src, dest);
-                    copiedCount++;
-                }
-            }
-        }
-        if (copiedCount > 0) {
-            userInfo(`✅ ${copiedCount} 个知识模板已复制到 .soloforge/knowledge/`);
-        }
+    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) {
@@ -627,16 +625,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({
@@ -662,6 +668,31 @@ async function cmdCheckWrite() {
         if (result.severity === "warning") {
             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) {
@@ -818,8 +849,7 @@ async function cmdValidate() {
     try {
         const { config, source } = await resolveProjectConfig(projectPath);
         if (source === "inferred") {
-            userInfo("ℹ️  未找到 .soloforge/config.yaml — 使用自动推断的配置。");
-            userInfo("   运行 'soloforge init --auto' 可持久化。");
+            userInfo("ℹ️  配置来源: 自动推断");
         }
         else {
             userInfo("✅ config.yaml 有效");
@@ -1240,6 +1270,97 @@ async function cmdAuditTemplateMechanisms() {
         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");
@@ -1447,14 +1568,14 @@ async function cmdSyncTemplates() {
     else {
         userInfo(apply ? "模板同步: apply 模式" : "模板同步: dry-run 模式（不写入文件）");
         userInfo(`  资产总数: ${assets.length}`);
-        userInfo(`  安全检查: ${safeCheck.safe ? "✓" : "✗"}`);
+        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 应用同步");
+            userInfo("  使用 --apply --confirm 应用同步；需确认表示 dry-run 发现现有用户资产，不会自动覆盖");
     }
     if (!syncResult.success)
         process.exit(1);
@@ -1830,8 +1951,8 @@ async function cmdValidateNewIssue() {
         userInfo(JSON.stringify(output, null, 2));
     }
     else {
-        userInfo(`问题演进门控: ${output.gate_status}`);
-        userInfo(`  已检查 ${allProblems.length} 个既有问题`);
+        userInfo(`需求演进检查: ${output.gate_status}`);
+        userInfo(`  已检查 ${allProblems.length} 个已有功能记录`);
         if (output.duplicate_detected) {
             userInfo(`  ⚠ 重复检测: 发现 ${output.duplicates.join(", ")}`);
             for (const d of matchedDetails) {
@@ -1844,7 +1965,7 @@ async function cmdValidateNewIssue() {
                 userInfo(`    - ${r}`);
         }
         if (output.can_proceed) {
-            userInfo(`  ✓ 可继续: 问题新增已通过演进门控 (候选ID: ${candidateId})`);
+            userInfo(`  ✓ 可继续: 需求新增已通过演进检查 (ID: ${candidateId})`);
         }
     }
     if (!output.can_proceed) {
@@ -2123,4 +2244,58 @@ function getArgValue(flag) {
         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,
+        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,
+    };
+    if (isJson) {
+        userJson(JSON.stringify(result, null, 2));
+    }
+    else {
+        userInfo("═══ 模板资产可见性审计报告 ═══");
+        userInfo(`总资产数:       ${report.total_assets}`);
+        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}`);
+    }
+}
 //# sourceMappingURL=soloforge.js.map