soloforge 1.2.7 → 1.2.9

package/dist/engine/config_precedence_contract.js

@@ -0,0 +1,948 @@
+/**
+ * Configuration Precedence Contract
+ *
+ * 定义配置优先级、覆盖规则、冲突检测和治理检查。
+ * 解决"配置一旦存在，谁优先"的问题。
+ *
+ * 优先级 (高→低):
+ *   user_task > cli_flag/mcp_param > confirmed_config > project_policy >
+ *   fingerprint > blueprint > product_profile > knowledge_default > global_default
+ *
+ * 上位约束 (guard) 不可被任何配置覆盖。
+ */
+import crypto from "node:crypto";
+import nodePath from "node:path";
+import nodeFs from "node:fs";
+import YAML from "yaml";
+// ── 优先级顺序 (索引=排名, 数值越小优先级越高) ──
+const PRECEDENCE_ORDER = [
+    "user_task",
+    "cli_flag",
+    "mcp_param",
+    "confirmed_config",
+    "project_policy",
+    "fingerprint",
+    "blueprint",
+    "product_profile",
+    "knowledge_default",
+    "global_default",
+];
+/** 证据元数据来源 — 映射到规范解析来源 */
+const EVIDENCE_SOURCE_MAP = {
+    user_declared: "confirmed_config",
+    confirmed: "confirmed_config",
+    detected: "fingerprint",
+};
+const SOURCE_LIFETIME = {
+    user_task: "task",
+    cli_flag: "single_invocation",
+    mcp_param: "single_invocation",
+    confirmed_config: "project_persistent",
+    project_policy: "project_persistent",
+    fingerprint: "task",
+    blueprint: "project_persistent",
+    product_profile: "global",
+    knowledge_default: "global",
+    global_default: "global",
+};
+// ── 上位约束 (不可被任何配置覆盖) ──
+/** 上位约束列表 — 这些约束不可被任何配置覆盖 */
+export const UPPER_BOUND_GUARDS = [
+    "enforced_guard",
+    "privacy_secret_policy",
+    "contract_state",
+    "command_safety",
+    "delivery_authorization",
+    "data_sovereignty",
+    "destructive_action_gate",
+    "human_sovereignty",
+];
+// ── 优先级规则 ──
+const PRECEDENCE_RULES = [
+    {
+        id: "pr-01",
+        higher_source: "user_task",
+        lower_source: "confirmed_config",
+        description: "用户本次指令优先于持久配置，但只在本次任务生效",
+        override_behavior: "selected",
+        requires_report: true,
+    },
+    {
+        id: "pr-02",
+        higher_source: "cli_flag",
+        lower_source: "confirmed_config",
+        description: "CLI 参数可临时覆盖 config，但不写入 config",
+        override_behavior: "selected",
+        requires_report: true,
+    },
+    {
+        id: "pr-03",
+        higher_source: "confirmed_config",
+        lower_source: "fingerprint",
+        description: "confirmed_config 优先于 fingerprint",
+        override_behavior: "overridden",
+        requires_report: true,
+    },
+    {
+        id: "pr-04",
+        higher_source: "confirmed_config",
+        lower_source: "product_profile",
+        description: "product_profile 只能补充默认，不覆盖用户确认配置",
+        override_behavior: "overridden",
+        requires_report: false,
+    },
+    {
+        id: "pr-05",
+        higher_source: "confirmed_config",
+        lower_source: "knowledge_default",
+        description: "knowledge_default 不能覆盖 config",
+        override_behavior: "overridden",
+        requires_report: false,
+    },
+    {
+        id: "pr-06",
+        higher_source: "fingerprint",
+        lower_source: "blueprint",
+        description: "fingerprint 优先于 blueprint，真实项目指纹出现后重新评估",
+        override_behavior: "overridden",
+        requires_report: true,
+    },
+    {
+        id: "pr-07",
+        higher_source: "fingerprint",
+        lower_source: "product_profile",
+        description: "fingerprint 优先于 product_profile 默认",
+        override_behavior: "overridden",
+        requires_report: false,
+    },
+    {
+        id: "pr-08",
+        higher_source: "fingerprint",
+        lower_source: "knowledge_default",
+        description: "fingerprint 优先于 knowledge_default",
+        override_behavior: "overridden",
+        requires_report: false,
+    },
+    {
+        id: "pr-09",
+        higher_source: "product_profile",
+        lower_source: "knowledge_default",
+        description: "product_profile 优先于 knowledge_default",
+        override_behavior: "overridden",
+        requires_report: false,
+    },
+    {
+        id: "pr-10",
+        higher_source: "knowledge_default",
+        lower_source: "global_default",
+        description: "knowledge_default 优先于 global_default",
+        override_behavior: "overridden",
+        requires_report: false,
+    },
+];
+const STALE_RULES = [
+    {
+        id: "stale-01",
+        trigger: "config_vs_fingerprint_mismatch",
+        severity: "warning",
+        description: "confirmed_config 与 fingerprint 冲突",
+        action: "不自动覆盖 confirmed_config，产生 stale/conflict report",
+    },
+    {
+        id: "stale-02",
+        trigger: "fingerprint_drift",
+        severity: "warning",
+        description: "fingerprint 发生变化（如 React→Vue），config 仍是旧值",
+        action: "产生 stale warning，不自动覆盖",
+    },
+    {
+        id: "stale-03",
+        trigger: "config_vs_blueprint_mismatch",
+        severity: "warning",
+        description: "blueprint 在空项目初期有效，真实项目指纹出现后应重新评估",
+        action: "提示重新评估，blueprint 降为 advisory",
+    },
+];
+// ── 查询函数 ──
+/** 列出所有配置优先级规则
+ * @returns 优先级规则数组
+ */
+export function listPrecedenceRules() {
+    return PRECEDENCE_RULES;
+}
+/** 列出所有配置过期检测规则
+ * @returns 过期规则数组
+ */
+export function listStaleRules() {
+    return STALE_RULES;
+}
+/** 获取配置来源的优先级排名（数值越小优先级越高）
+ * @param source - 配置来源
+ * @returns 优先级排名索引
+ */
+export function getPrecedenceRank(source) {
+    return PRECEDENCE_ORDER.indexOf(source);
+}
+/** 获取配置来源的生命周期
+ * @param source - 配置来源
+ * @returns 生命周期类型
+ */
+export function getSourceLifetime(source) {
+    return SOURCE_LIFETIME[source];
+}
+/** 判断来源 a 的优先级是否高于来源 b
+ * @param a - 配置来源 a
+ * @param b - 配置来源 b
+ * @returns a 是否优先级更高
+ */
+export function isHigherPriority(a, b) {
+    return getPrecedenceRank(a) < getPrecedenceRank(b);
+}
+// ── 解析 ──
+/** 解析单个配置字段 — 按优先级排序候选值并检测冲突
+ * @param fieldPath - 字段路径
+ * @param candidates - 候选值列表
+ * @returns 配置解析报告
+ */
+export function resolveConfigField(fieldPath, candidates) {
+    const sorted = [...candidates].sort((a, b) => getPrecedenceRank(a.source) - getPrecedenceRank(b.source));
+    const selected = sorted[0];
+    const conflicts = [];
+    for (let i = 1; i < sorted.length; i++) {
+        const candidate = sorted[i];
+        if (JSON.stringify(candidate.value) !== JSON.stringify(selected.value)) {
+            conflicts.push({
+                source_a: selected.source,
+                source_b: candidate.source,
+                field_path: fieldPath,
+                reason: buildConflictReason(selected.source, candidate.source, fieldPath),
+                requires_human: candidate.source === "confirmed_config" && selected.source === "fingerprint"
+                    ? false
+                    : isHighStakesField(fieldPath),
+            });
+        }
+    }
+    return {
+        field_path: fieldPath,
+        selected,
+        candidates: sorted,
+        conflicts,
+        lifetime: SOURCE_LIFETIME[selected.source],
+    };
+}
+/** 解析所有配置字段
+ * @param fieldCandidates - 字段路径到候选值列表的映射
+ * @returns 所有字段的解析报告数组
+ */
+export function resolveAllFields(fieldCandidates) {
+    const reports = [];
+    for (const [fieldPath, candidates] of Object.entries(fieldCandidates)) {
+        if (candidates.length > 0) {
+            reports.push(resolveConfigField(fieldPath, candidates));
+        }
+    }
+    return reports;
+}
+/** 检查上位约束是否阻止该配置
+ * @param report - 配置解析报告
+ * @param guardId - 上位约束 ID
+ * @returns 约束检查结果
+ */
+export function checkGuardOverride(report, guardId) {
+    if (isGuardProtectedField(report.field_path, guardId)) {
+        console.error("[soloForge] 配置优先级: 字段 %s 被上位约束 %s 阻止", report.field_path, guardId);
+        return {
+            blocked: true,
+            report: {
+                ...report,
+                overridden_by_guard: guardId,
+            },
+        };
+    }
+    return { blocked: false, report };
+}
+function isGuardProtectedField(fieldPath, guard) {
+    const GUARD_FIELDS = {
+        enforced_guard: ["*"],
+        privacy_secret_policy: ["delivery", "secrets", "accounts", "external_integrations"],
+        command_safety: ["destructive_command_policy", "verify_timeout"],
+        delivery_authorization: ["delivery.auto_push", "delivery.auto_pr", "delivery.deploy"],
+        data_sovereignty: ["core_knowledge", "compliance", "privacy_policy"],
+        destructive_action_gate: ["destructive_command_policy", "scope_exclusion"],
+    };
+    const protectedFields = GUARD_FIELDS[guard] ?? [];
+    if (protectedFields.includes("*"))
+        return true;
+    return protectedFields.some((f) => fieldPath.startsWith(f));
+}
+// ── 过期检测 ──
+/** 检测配置是否过期 — 比较确认值与指纹值是否一致
+ * @param confirmedValue - 已确认的配置值
+ * @param fingerprintValue - 当前指纹值
+ * @returns 是否过期及警告信息
+ */
+export function detectStaleConfig(confirmedValue, fingerprintValue) {
+    if (confirmedValue.source !== "confirmed_config")
+        return { isStale: false, warning: "" };
+    if (fingerprintValue.source !== "fingerprint")
+        return { isStale: false, warning: "" };
+    if (JSON.stringify(confirmedValue.value) !== JSON.stringify(fingerprintValue.value)) {
+        console.error("[soloForge] 配置优先级: 字段 %s 配置过期，确认值与指纹不一致", confirmedValue.field_path);
+        return {
+            isStale: true,
+            warning: `config_stale_warning: ${confirmedValue.field_path} 的确认值 (${JSON.stringify(confirmedValue.value)}) 与当前 fingerprint (${JSON.stringify(fingerprintValue.value)}) 不一致 — 建议重新确认`,
+        };
+    }
+    return { isStale: false, warning: "" };
+}
+// ── 字段分类写入规则 ──
+/** C 类字段列表 — 仅允许人工确认写入，永不自动写入 */
+export const C_CLASS_FIELDS = [
+    "product_mapping",
+    "delivery.auto_push",
+    "delivery.auto_pr",
+    "delivery.deploy",
+    "secrets",
+    "accounts",
+    "production_database",
+    "destructive_command_policy",
+    "external_integrations",
+    "compliance_policy",
+    "privacy_policy",
+    "core_knowledge_sovereignty",
+];
+/** 判断字段是否为 C 类字段
+ * @param fieldPath - 字段路径
+ * @returns 是否为 C 类字段
+ */
+export function isCClassField(fieldPath) {
+    return C_CLASS_FIELDS.some(f => fieldPath.startsWith(f));
+}
+/** 获取配置字段的分类（C 类或 B 类）
+ * @param fieldPath - 字段路径
+ * @param explicitClass - 显式指定的分类（可选）
+ * @returns 字段分类
+ */
+export function getConfigFieldClass(fieldPath, explicitClass) {
+    if (explicitClass)
+        return explicitClass;
+    if (isCClassField(fieldPath))
+        return "C";
+    return "B";
+}
+/** 判断字段是否允许自动写入
+ * @param fieldPath - 字段路径
+ * @param fieldClass - 字段分类
+ * @param source - 配置来源
+ * @returns 是否允许及原因
+ */
+export function canAutoWriteField(fieldPath, fieldClass, source) {
+    const canonical = mapEvidenceSource(source);
+    // C 类: 永不自动写入 (only confirmed_config allowed)
+    if (fieldClass === "C" || isCClassField(fieldPath)) {
+        if (canonical !== "confirmed_config") {
+            return { allowed: false, reason: `C 类字段 ${fieldPath} 不得自动写入，必须 user_declared 或 confirmed` };
+        }
+    }
+    // B 类: 需要高置信 (confirmed_config or fingerprint)
+    if (fieldClass === "B") {
+        if (canonical !== "fingerprint" && canonical !== "confirmed_config") {
+            return { allowed: false, reason: `B 类字段 ${fieldPath} 需要高置信来源 (detected/user_declared/confirmed)` };
+        }
+    }
+    // CLI flag 不静默写入 config
+    if (source === "cli_flag" || source === "mcp_param") {
+        return { allowed: false, reason: "CLI/MCP 参数不静默写入 config，仅对本次 invocation/task 有效" };
+    }
+    return { allowed: true, reason: "" };
+}
+// ── 证据来源映射 ──
+/** 将证据元数据来源映射为规范配置来源
+ * @param source - 原始来源标识
+ * @returns 规范配置来源
+ */
+export function mapEvidenceSource(source) {
+    return EVIDENCE_SOURCE_MAP[source] ?? source;
+}
+// ── 证据工厂 ──
+/** 创建配置值证据
+ * @param fieldPath - 字段路径
+ * @param value - 配置值
+ * @param source - 配置来源
+ * @param confidence - 置信度
+ * @param evidenceRef - 证据引用（可选）
+ * @returns 配置值证据
+ */
+export function createConfigValueEvidence(fieldPath, value, source, confidence, evidenceRef) {
+    return {
+        field_path: fieldPath,
+        value,
+        source,
+        confidence,
+        evidence_ref: evidenceRef,
+        updated_at: new Date().toISOString(),
+    };
+}
+/** 创建配置证据条目
+ * @param fieldPath - 字段路径
+ * @param value - 配置值
+ * @param source - 配置来源
+ * @param options - 可选参数
+ * @param options.confidence - 置信度（可选，默认 1.0）
+ * @param options.evidence_refs - 证据引用列表（可选）
+ * @param options.confirmed_by - 确认者（可选）
+ * @param options.expires_at - 过期时间（可选）
+ * @returns 配置证据条目
+ */
+/**
+ * 创建配置证据条目。
+ * @param field - 配置字段名
+ * @param source - 证据来源
+ * @param value - 字段值
+ * @returns 证据条目
+ */
+export function createConfigEvidenceEntry(fieldPath, value, source, options) {
+    return {
+        field_path: fieldPath,
+        value_hash: hashValue(value),
+        source,
+        confidence: options?.confidence ?? 1.0,
+        evidence_refs: options?.evidence_refs ?? [],
+        confirmed_by: options?.confirmed_by,
+        lifetime: SOURCE_LIFETIME[source],
+        collected_at: new Date().toISOString(),
+        expires_at: options?.expires_at,
+    };
+}
+/** 计算值的简易哈希
+ * @param value - 待哈希的值
+ * @returns 十六进制哈希字符串
+ */
+export function hashValue(value) {
+    const str = JSON.stringify(value);
+    return crypto.createHash("sha256").update(str).digest("hex").slice(0, 16);
+}
+// ── 中文解释 ──
+/** 生成配置字段解析结果的中文解释
+ * @param report - 配置解析报告
+ * @returns 格式化的中文解释文本
+ */
+export function explainField(report) {
+    const lines = [];
+    const sel = report.selected;
+    lines.push(`字段: ${report.field_path}`);
+    lines.push(`当前值: ${JSON.stringify(sel.value)}`);
+    lines.push(`来源: ${sourceLabel(sel.source)} (优先级 ${getPrecedenceRank(sel.source) + 1}/${PRECEDENCE_ORDER.length})`);
+    lines.push(`生命周期: ${lifetimeLabel(report.lifetime)}`);
+    lines.push(`置信度: ${sel.confidence}`);
+    if (sel.evidence_ref) {
+        lines.push(`证据: ${sel.evidence_ref}`);
+    }
+    if (report.candidates.length > 1) {
+        lines.push(`其他候选:`);
+        for (let i = 1; i < report.candidates.length; i++) {
+            const c = report.candidates[i];
+            lines.push(`  - ${sourceLabel(c.source)}: ${JSON.stringify(c.value)} (未被采用: ${notSelectedReason(report, c)})`);
+        }
+    }
+    if (report.overridden_by_guard) {
+        lines.push(`⚠️ 被上位约束 ${report.overridden_by_guard} 阻止`);
+    }
+    if (report.conflicts.length > 0) {
+        lines.push(`冲突:`);
+        for (const c of report.conflicts) {
+            lines.push(`  - ${sourceLabel(c.source_a)} vs ${sourceLabel(c.source_b)}: ${c.reason}`);
+            if (c.requires_human) {
+                lines.push(`    需要人工确认`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+function sourceLabel(source) {
+    const labels = {
+        user_task: "用户本次指令",
+        cli_flag: "CLI 参数",
+        mcp_param: "MCP 参数",
+        confirmed_config: "已确认配置 (config.yaml)",
+        project_policy: "项目策略",
+        fingerprint: "文件指纹探测",
+        blueprint: "项目蓝图",
+        product_profile: "产品画像默认",
+        knowledge_default: "知识库默认",
+        global_default: "全局默认",
+    };
+    return labels[source];
+}
+function lifetimeLabel(lifetime) {
+    const labels = {
+        single_invocation: "单次调用",
+        task: "本次任务",
+        project_persistent: "项目持久",
+        global: "全局",
+    };
+    return labels[lifetime];
+}
+function notSelectedReason(report, candidate) {
+    const selectedRank = getPrecedenceRank(report.selected.source);
+    const candidateRank = getPrecedenceRank(candidate.source);
+    if (candidateRank > selectedRank) {
+        return `优先级低于 ${sourceLabel(report.selected.source)}`;
+    }
+    return "值相同，无冲突";
+}
+function buildConflictReason(higher, lower, fieldPath) {
+    return `${sourceLabel(higher)} 与 ${sourceLabel(lower)} 在字段 ${fieldPath} 上存在冲突`;
+}
+function isHighStakesField(fieldPath) {
+    const highStakes = [
+        "delivery", "scope", "product_profile", "secrets", "accounts",
+        "production_database", "destructive_command_policy", "compliance",
+    ];
+    return highStakes.some((f) => fieldPath.startsWith(f));
+}
+// ── CLI 参数写入守卫 ──
+/** 判断来源是否可安全写入配置（非 CLI/MCP 临时参数）
+ * @param source - 配置来源
+ * @returns 是否可安全写入
+ */
+export function isCliWriteSafe(source) {
+    return source !== "cli_flag" && source !== "mcp_param";
+}
+// ── 治理校验 ──
+/** 执行配置优先级治理校验
+ * @param reports - 配置解析报告列表
+ * @param entries - 配置证据条目列表
+ * @returns 治理发现列表
+ */
+export function validateConfigPrecedence(reports, entries) {
+    console.error("[soloForge] 配置优先级: 开始治理校验，共 %d 个报告", reports.length);
+    const findings = [];
+    // 规则 1: CLI flag 不静默写入 config
+    for (const e of entries) {
+        if (e.source === "cli_flag" || e.source === "mcp_param") {
+            if (e.lifetime === "project_persistent") {
+                findings.push({
+                    severity: "hard_fail",
+                    rule: "gc-cli-no-persist",
+                    field_path: e.field_path,
+                    message: `CLI/MCP 参数 (${e.source}) 不应持久化到 config — ${e.field_path}`,
+                });
+            }
+        }
+    }
+    // 规则 2: fingerprint 不覆盖 confirmed_config
+    for (const r of reports) {
+        if (r.selected.source === "fingerprint") {
+            const hasConfirmed = r.candidates.some((c) => c.source === "confirmed_config");
+            if (hasConfirmed) {
+                findings.push({
+                    severity: "hard_fail",
+                    rule: "gc-fingerprint-no-override",
+                    field_path: r.field_path,
+                    message: `fingerprint 不应覆盖 confirmed_config — ${r.field_path}`,
+                });
+            }
+        }
+    }
+    // 规则 3: product_profile 不覆盖 config
+    for (const r of reports) {
+        if (r.selected.source === "product_profile") {
+            const hasConfirmed = r.candidates.some((c) => c.source === "confirmed_config");
+            if (hasConfirmed) {
+                findings.push({
+                    severity: "hard_fail",
+                    rule: "gc-profile-no-override",
+                    field_path: r.field_path,
+                    message: `product_profile 不应覆盖 confirmed_config — ${r.field_path}`,
+                });
+            }
+        }
+    }
+    // 规则 4: knowledge_default 不覆盖 config
+    for (const r of reports) {
+        if (r.selected.source === "knowledge_default") {
+            const hasConfig = r.candidates.some((c) => c.source === "confirmed_config" || c.source === "project_policy");
+            if (hasConfig) {
+                findings.push({
+                    severity: "hard_fail",
+                    rule: "gc-knowledge-no-override",
+                    field_path: r.field_path,
+                    message: `knowledge_default 不应覆盖 config — ${r.field_path}`,
+                });
+            }
+        }
+    }
+    // 规则 5: C 类字段不得自动写入 — only confirmed_config (from user_declared/confirmed) allowed
+    for (const e of entries) {
+        if (isCClassField(e.field_path)) {
+            const canonical = mapEvidenceSource(e.source);
+            if (canonical !== "confirmed_config") {
+                findings.push({
+                    severity: "hard_fail",
+                    rule: "gc-c-class-no-auto",
+                    field_path: e.field_path,
+                    message: `C 类字段 ${e.field_path} 不得自动写入 (当前来源: ${e.source})`,
+                });
+            }
+        }
+    }
+    // 规则 6: guard 不可被配置绕过 — check that guard-blocked fields stay blocked
+    for (const r of reports) {
+        if (r.overridden_by_guard) {
+            findings.push({
+                severity: "advisory",
+                rule: "gc-guard-block",
+                field_path: r.field_path,
+                message: `字段 ${r.field_path} 被上位约束 ${r.overridden_by_guard} 保护`,
+            });
+        }
+    }
+    // 规则 7: conflict 必须被报告 (advisory)
+    for (const r of reports) {
+        if (r.conflicts.length > 0) {
+            const configFpConflict = r.conflicts.find((c) => c.source_a === "confirmed_config" && c.source_b === "fingerprint");
+            if (configFpConflict) {
+                findings.push({
+                    severity: "advisory",
+                    rule: "gc-conflict-report",
+                    field_path: r.field_path,
+                    message: `字段 ${r.field_path} 存在 confirmed_config 与 fingerprint 冲突，已自动处理`,
+                });
+            }
+        }
+    }
+    // 规则 9: value_hash 不匹配 — 证据条目的 hash 必须与解析值一致
+    for (const r of reports) {
+        const entry = entries.find((e) => e.field_path === r.field_path);
+        if (entry) {
+            const computed = hashValue(r.selected.value);
+            if (entry.value_hash !== computed) {
+                findings.push({
+                    severity: "hard_fail",
+                    rule: "gc-evidence-hash-mismatch",
+                    field_path: r.field_path,
+                    message: `字段 ${r.field_path} evidence value_hash 不匹配 (entry=${entry.value_hash}, computed=${computed}) — evidence 可能过期`,
+                });
+            }
+        }
+    }
+    // 规则 10: blueprint 与 fingerprint/confirmed_config 不一致 (advisory)
+    for (const r of reports) {
+        const blueprintCandidate = r.candidates.find((c) => c.source === "blueprint");
+        if (!blueprintCandidate)
+            continue;
+        const higherCandidate = r.candidates.find((c) => c.source === "fingerprint" || c.source === "confirmed_config");
+        if (!higherCandidate)
+            continue;
+        if (JSON.stringify(blueprintCandidate.value) !== JSON.stringify(higherCandidate.value)) {
+            findings.push({
+                severity: "advisory",
+                rule: "gc-blueprint-mismatch",
+                field_path: r.field_path,
+                message: `字段 ${r.field_path} blueprint (${JSON.stringify(blueprintCandidate.value)}) 与 ${higherCandidate.source} (${JSON.stringify(higherCandidate.value)}) 不一致 — blueprint 可能需要更新`,
+            });
+        }
+    }
+    // 规则 8: 每个 resolved 字段应有 evidence
+    for (const r of reports) {
+        const hasEntry = entries.some((e) => e.field_path === r.field_path);
+        if (!hasEntry) {
+            findings.push({
+                severity: "advisory",
+                rule: "gc-evidence-required",
+                field_path: r.field_path,
+                message: `字段 ${r.field_path} 已解析但缺少 ConfigEvidenceEntry`,
+            });
+        }
+    }
+    if (findings.length > 0) {
+        const hardFails = findings.filter(f => f.severity === "hard_fail");
+        if (hardFails.length > 0) {
+            console.error("[soloForge] 配置优先级: 治理校验发现 %d 个 hard_fail", hardFails.length);
+        }
+    }
+    return findings;
+}
+// ── 中文冲突报告 ──
+/** 生成配置冲突的中文报告
+ * @param report - 配置解析报告
+ * @returns 格式化的冲突报告文本
+ */
+export function buildConflictReport(report) {
+    const lines = [];
+    lines.push(`配置冲突报告: ${report.field_path}`);
+    lines.push(`当前采用: ${sourceLabel(report.selected.source)} = ${JSON.stringify(report.selected.value)}`);
+    lines.push(`生命周期: ${lifetimeLabel(report.lifetime)}`);
+    for (const c of report.conflicts) {
+        lines.push(`冲突: ${sourceLabel(c.source_a)} vs ${sourceLabel(c.source_b)}`);
+        lines.push(`  原因: ${c.reason}`);
+        if (c.requires_human) {
+            lines.push(`  ⚠️ 需要人工确认`);
+        }
+    }
+    if (report.overridden_by_guard) {
+        lines.push(`⚠️ 被上位约束 ${report.overridden_by_guard} 阻止`);
+    }
+    lines.push(`建议: ${buildResolutionAdvice(report)}`);
+    return lines.join("\n");
+}
+function buildResolutionAdvice(report) {
+    if (report.overridden_by_guard) {
+        return "上位约束生效，不可通过配置修改";
+    }
+    if (report.selected.source === "user_task") {
+        return "本次用户指令优先，仅对本次任务生效，不写入 config";
+    }
+    if (report.selected.source === "cli_flag" || report.selected.source === "mcp_param") {
+        return "CLI/MCP 参数仅对本次调用生效，不写入 config。如需持久化请使用 config confirm";
+    }
+    if (report.conflicts.some((c) => c.source_b === "fingerprint")) {
+        return "fingerprint 变化未自动覆盖 confirmed_config。如需更新请使用 soloforge init --interactive";
+    }
+    return "当前配置已正确解析";
+}
+export function resolveConfigFromSources(fields) {
+    const resolutions = [];
+    const reports = [];
+    const warnings = [];
+    for (const [fieldPath, rawSources] of Object.entries(fields)) {
+        let candidates;
+        // 检测旧格式与新 FieldCandidates 格式
+        if (Array.isArray(rawSources)) {
+            candidates = rawSources;
+        }
+        else {
+            // 旧格式: { config_value, fingerprint_value, user_override }
+            const sources = rawSources;
+            candidates = [];
+            if (sources.user_override !== undefined) {
+                candidates.push(createConfigValueEvidence(fieldPath, sources.user_override, "user_task", 1.0));
+            }
+            if (sources.config_value !== undefined) {
+                candidates.push(createConfigValueEvidence(fieldPath, sources.config_value, "confirmed_config", 0.9));
+            }
+            if (sources.fingerprint_value !== undefined) {
+                candidates.push(createConfigValueEvidence(fieldPath, sources.fingerprint_value, "fingerprint", 0.8));
+            }
+        }
+        if (candidates.length === 0)
+            continue;
+        const report = resolveConfigField(fieldPath, candidates);
+        reports.push(report);
+        const resolution = {
+            field_path: fieldPath,
+            resolved_value: report.selected.value,
+            source: report.selected.source,
+        };
+        // 检测过期: confirmed_config 与 fingerprint 不一致
+        const configEv = candidates.find(c => c.source === "confirmed_config");
+        const fpEv = candidates.find(c => c.source === "fingerprint");
+        if (configEv && fpEv) {
+            const stale = detectStaleConfig(configEv, fpEv);
+            if (stale.isStale) {
+                resolution.stale_warning = stale.warning;
+                warnings.push(stale.warning);
+            }
+        }
+        if (report.conflicts.length > 0) {
+            resolution.conflict_report = buildConflictReport(report);
+        }
+        resolutions.push(resolution);
+    }
+    return { resolutions, reports, warnings };
+}
+const DEFAULT_CONFIG_FIELDS = [
+    "product_profile",
+    "tech_stack.backend.framework",
+    "tech_stack.frontend.framework",
+];
+/**
+ * 共享函数，解析当前项目配置。
+ * 读取 config.yaml、实时指纹、证据条目，并接受所有候选来源。
+ * expand()、配置解析/解释、校验、状态、治理都必须复用此函数 — 不可重复逻辑。
+ *
+ * 证据条目不是候选值 — 仅用于校验：
+ * 检查来源/生命周期合规性和 value_hash 匹配。
+ *
+ * product_profile: fingerprint 候选仅来自确定性产品证据
+ * (package.json soloforge.product_profile)，不使用技术形态推断。
+ */
+export async function resolveCurrentProjectConfigReports(projectPath, options) {
+    console.error("[soloForge] 配置优先级: 开始解析项目配置");
+    const { resolveProjectConfig } = await import("../knowledge/loader.js");
+    const { detectFingerprint } = await import("./zero_config_init.js");
+    const { loadConfigEvidenceEntries } = await import("../bin/config_commands.js");
+    const { config } = await resolveProjectConfig(projectPath);
+    let fp = null;
+    try {
+        fp = await detectFingerprint(projectPath);
+    }
+    catch (e) {
+        console.error("[soloForge] 配置优先级: 项目指纹检测失败 —", e);
+    }
+    // 证据条目仅用于校验 — 不作为候选值
+    const entries = loadConfigEvidenceEntries(projectPath);
+    const fields = options?.fields ?? DEFAULT_CONFIG_FIELDS;
+    const fieldCandidates = {};
+    for (const fieldPath of fields) {
+        const candidates = [];
+        // 1. user_task 覆盖 (最高优先级)
+        if (options?.user_task_overrides?.[fieldPath] !== undefined) {
+            candidates.push(createConfigValueEvidence(fieldPath, options.user_task_overrides[fieldPath], "user_task", 1.0, "user intent"));
+        }
+        // 2. cli_flag 覆盖
+        if (options?.cli_overrides?.[fieldPath] !== undefined) {
+            candidates.push(createConfigValueEvidence(fieldPath, options.cli_overrides[fieldPath], "cli_flag", 1.0, "cli flag"));
+        }
+        // 3. mcp_param 覆盖
+        if (options?.mcp_overrides?.[fieldPath] !== undefined) {
+            candidates.push(createConfigValueEvidence(fieldPath, options.mcp_overrides[fieldPath], "mcp_param", 1.0, "mcp param"));
+        }
+        // 4. confirmed_config 来自 config.yaml
+        const configVal = getConfigFieldValue(config, fieldPath);
+        if (configVal !== undefined) {
+            candidates.push(createConfigValueEvidence(fieldPath, configVal, "confirmed_config", 0.9, "config.yaml"));
+        }
+        // 5. project_policy — 从 .soloforge/policy.yaml 加载 (如存在)
+        const policyVal = loadProjectPolicyField(projectPath, fieldPath);
+        if (policyVal !== undefined) {
+            candidates.push(createConfigValueEvidence(fieldPath, policyVal, "project_policy", 0.85, "policy.yaml"));
+        }
+        // 6. fingerprint — 不用于 product_profile (不进行技术形态推断)
+        if (fp && fieldPath !== "product_profile") {
+            const fpVal = getFingerprintFieldValue(fp, fieldPath);
+            if (fpVal !== undefined) {
+                candidates.push(createConfigValueEvidence(fieldPath, fpVal, "fingerprint", 0.8, "file detection"));
+            }
+        }
+        // product_profile: 仅使用 package.json soloforge.product_profile 的确定性证据
+        if (fp && fieldPath === "product_profile") {
+            const productEvidence = detectProductEvidenceFromFingerprint(fp);
+            if (productEvidence !== null) {
+                candidates.push(createConfigValueEvidence(fieldPath, productEvidence.value, "fingerprint", 0.8, productEvidence.evidence[0]));
+            }
+        }
+        // 7. blueprint — 从 .soloforge/blueprint.yaml 加载 (如存在)
+        const blueprintVal = loadBlueprintField(projectPath, fieldPath);
+        if (blueprintVal !== undefined) {
+            candidates.push(createConfigValueEvidence(fieldPath, blueprintVal, "blueprint", 0.6, "blueprint"));
+        }
+        // 8. product_profile 作为默认值 — 仅在其他候选均未提供值时使用
+        // (product_profile 来自知识文件，非技术形态)
+        if (fieldPath === "product_profile" && candidates.length === 0) {
+            const profileDefault = loadProductProfileDefault(projectPath);
+            if (profileDefault !== undefined) {
+                candidates.push(createConfigValueEvidence(fieldPath, profileDefault, "product_profile", 0.4, "product profile default"));
+            }
+        }
+        // 9. knowledge_default (知识库默认)
+        const knowledgeDefault = loadKnowledgeDefault(projectPath, fieldPath);
+        if (knowledgeDefault !== undefined && candidates.length === 0) {
+            candidates.push(createConfigValueEvidence(fieldPath, knowledgeDefault, "knowledge_default", 0.3, "knowledge default"));
+        }
+        // 10. global_default — 硬编码回退值
+        const globalDefault = getGlobalDefault(fieldPath);
+        if (globalDefault !== undefined && candidates.length === 0) {
+            candidates.push(createConfigValueEvidence(fieldPath, globalDefault, "global_default", 0.1, "global default"));
+        }
+        fieldCandidates[fieldPath] = candidates;
+    }
+    const { resolutions, reports, warnings } = resolveConfigFromSources(fieldCandidates);
+    if (warnings.length > 0) {
+        console.error("[soloForge] 配置优先级: 发现 %d 个配置警告", warnings.length);
+    }
+    console.error("[soloForge] 配置优先级: 解析完成，共 %d 个字段", resolutions.length);
+    return { reports, resolutions, warnings, entries };
+}
+// ── 来源加载辅助函数 ──
+function loadProjectPolicyField(projectPath, fieldPath) {
+    const policyPath = nodePath.join(projectPath, ".soloforge", "policy.yaml");
+    try {
+        const raw = nodeFs.readFileSync(policyPath, "utf-8");
+        const parsed = YAML.parse(raw);
+        return getConfigFieldValue(parsed ?? {}, fieldPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function loadBlueprintField(projectPath, fieldPath) {
+    const blueprintPath = nodePath.join(projectPath, ".soloforge", "blueprint.yaml");
+    try {
+        const raw = nodeFs.readFileSync(blueprintPath, "utf-8");
+        const parsed = YAML.parse(raw);
+        return getConfigFieldValue(parsed ?? {}, fieldPath);
+    }
+    catch {
+        return undefined;
+    }
+}
+function loadProductProfileDefault(projectPath) {
+    const profileDir = nodePath.join(projectPath, ".soloforge", "knowledge", "product_profiles");
+    try {
+        const files = nodeFs.readdirSync(profileDir).filter(f => f.endsWith(".md") || f.endsWith(".yaml"));
+        if (files.length > 0)
+            return files[0].replace(/.(md|yaml)$/, "");
+    }
+    catch { }
+    return undefined;
+}
+function loadKnowledgeDefault(projectPath, fieldPath) {
+    const defaultsPath = nodePath.join(projectPath, ".soloforge", "knowledge", "defaults.yaml");
+    try {
+        const raw = nodeFs.readFileSync(defaultsPath, "utf-8");
+        const parsed = YAML.parse(raw);
+        if (parsed && typeof parsed === "object")
+            return getConfigFieldValue(parsed, fieldPath);
+    }
+    catch { }
+    return undefined;
+}
+function getGlobalDefault(fieldPath) {
+    const defaults = {
+        "product_profile": "default",
+    };
+    return defaults[fieldPath];
+}
+function getConfigFieldValue(obj, fieldPath) {
+    const parts = fieldPath.split(".");
+    let current = obj;
+    for (const p of parts) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[p];
+    }
+    return current;
+}
+function getFingerprintFieldValue(fp, fieldPath) {
+    switch (fieldPath) {
+        case "tech_stack.backend.framework":
+            return fp.backend?.framework || undefined;
+        case "tech_stack.frontend.framework":
+            return fp.frontend?.framework || undefined;
+        default:
+            return undefined;
+    }
+}
+function detectProductEvidenceFromFingerprint(fp) {
+    // 委托给 zero_config_init 的 detectProductEvidence
+    // 由于该函数未导出，此处复制其逻辑：
+    // 仅 package.json soloforge.product_profile 作为确定性证据
+    if (!fp.project_root)
+        return null;
+    const pkgPath = nodePath.join(fp.project_root, "package.json");
+    try {
+        const raw = nodeFs.readFileSync(pkgPath, "utf-8");
+        const data = JSON.parse(raw);
+        if (data.soloforge && typeof data.soloforge.product_profile === "string") {
+            const val = data.soloforge.product_profile;
+            if (val.length > 0) {
+                return { value: val, evidence: ["package.json soloforge.product_profile"] };
+            }
+        }
+    }
+    catch { }
+    return null;
+}
+//# sourceMappingURL=config_precedence_contract.js.map