soloforge 1.2.7 → 1.2.9

package/dist/engine/intent_expander.js

@@ -1,7 +1,53 @@
 import Handlebars from "handlebars";
+/**
+ * 意图膨胀器 — 将分类结果扩展为包含完整上下文的 AI 执行 prompt。
+ *
+ * 根据 route_decision.execution_shape 选择不同 prompt 模板:
+ * - code_execution_prompt: 代码修改任务
+ * - single_artifact_prompt: 单产物生成任务
+ * - source_extraction_prompt: 源码/材料提取任务
+ * - read_only_analysis_prompt: 只读分析任务
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fss from "node:fs";
+import matter from "gray-matter";
 import { detectConventions } from "./convention_detector.js";
-// AI 执行 prompt 模板: 包含任务描述、项目上下文、知识匹配、scope 约束、验收标准
-const PROMPT_TEMPLATE = Handlebars.compile(`## 任务
+import { selectPromptTemplate } from "./intent_router.js";
+import { enforceKnowledgeInjectionBoundary, validateInjectionReport, getInjectedEntryIds } from "./knowledge_injection_boundary.js";
+import { createInputMaterial, createIngestionEvidence, buildPromptInjectionPlan, classifyIngestionStatus, } from "./input_material_contract_registry.js";
+import { resolveWorkflow } from "./workflow_contract_registry.js";
+import { createOutputArtifact, getDefaultArtifactPath } from "./artifact_contract_registry.js";
+import { findToolInvocationContractByName } from "./tool_invocation_contract_registry.js";
+import { resolveCurrentProjectConfigReports } from "./config_precedence_contract.js";
+import { evaluatePrivacyGate, redactSensitiveText, } from "./privacy_secret_contract.js";
+import { getTaskLevel, getRequiredPrinciples, getEnforcementLevel, listCorePrinciples } from "./core_engineering_principles.js";
+import { listMechanismLayerMaps } from "./dual_layer_mechanism_registry.js";
+// 配置优先级：委托给 resolveCurrentProjectConfigReports (shared function)
+// ── 产物类型映射 ──
+function mapToArtifactKind(kind) {
+    if (kind === "unknown")
+        return "custom";
+    if (kind === "design_doc")
+        return "design_doc";
+    if (kind === "api_spec")
+        return "api_spec";
+    if (kind === "task_breakdown")
+        return "task_breakdown";
+    if (kind === "root_cause")
+        return "root_cause";
+    if (kind === "acceptance_checklist")
+        return "acceptance_checklist";
+    if (kind === "interaction_spec")
+        return "interaction_spec";
+    if (kind === "domain_model")
+        return "domain_model";
+    // 其他类型均为合法的 ArtifactKind 值
+    return kind;
+}
+// ── Prompt 模板 ──
+// 1. code_execution_prompt: 允许修改业务源码，需要 scope 和验证
+const CODE_EXECUTION_TEMPLATE = Handlebars.compile(`## 任务
 {{intent}}
 
 ## 项目上下文
@@ -58,83 +104,747 @@ const PROMPT_TEMPLATE = Handlebars.compile(`## 任务
 **注意**: 当前无领域知识匹配，请保守操作，只修改必要文件。
 {{/if}}
 `);
+// 2. single_artifact_prompt: 默认不允许修改业务源码，必须有 output_artifact.path
+const SINGLE_ARTIFACT_TEMPLATE = Handlebars.compile(`## 任务
+{{intent}}
+
+## 产物要求
+- 产物类型: {{output_artifact.kind}}
+- 输出路径: {{output_artifact.path}}
+{{#if output_artifact.template}}
+- 参考模板: {{output_artifact.template}}
+{{/if}}
+
+## 项目上下文
+- 技术栈: {{tech_stack}}
+- 产品类型: {{product_profile}}
+
+{{#if matched_knowledge}}
+## 适用知识
+{{#each matched_knowledge}}
+### {{this.name}}
+{{this.content}}
+
+{{/each}}
+{{/if}}
+
+## 约束
+- 默认不允许修改业务源码
+- 只允许写入指定产物路径
+- 产物必须结构完整、证据充分、可交接
+
+## 验收标准
+{{#if acceptance.automated}}
+### 自动验证
+{{#each acceptance.automated}}
+- [{{this.id}}] {{this.description}}
+{{/each}}
+{{/if}}
+### 人工验证
+- 产物完整性: 章节齐全，无空白占位
+- 证据充分: 关键结论有引用或出处
+- 可交接性: 下游可基于此产物继续工作
+
+{{#if degraded}}
+**注意**: 当前无专用模板，请按同类通用产物结构输出。
+{{/if}}
+`);
+// 3. source_extraction_prompt: 只读输入材料，不允许修改项目源码
+const SOURCE_EXTRACTION_TEMPLATE = Handlebars.compile(`## 任务
+{{intent}}
+
+## 输入材料
+{{#each input_materials}}
+- 类型: {{this.kind}}{{#if this.path}}，路径: {{this.path}}{{/if}}{{#if this.ingestion_status}}，状态: {{this.ingestion_status}}{{/if}}（只读）
+{{/each}}
+
+{{#if input_material_contract_notes}}
+## 输入材料契约检查
+{{#each input_material_contract_notes}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+## 产物要求
+- 产物类型: {{output_artifact.kind}}
+- 输出路径: {{output_artifact.path}}
+{{#if output_artifact.template}}
+- 参考模板: {{output_artifact.template}}
+{{/if}}
+{{#if pipeline_hint}}
+- 流程提示: {{pipeline_hint}}
+{{/if}}
+
+{{#if matched_knowledge}}
+## 适用知识
+{{#each matched_knowledge}}
+### {{this.name}}
+{{this.content}}
+
+{{/each}}
+{{/if}}
+
+## 约束
+- 输入材料只读，不得修改
+- 不允许修改项目业务源码 (src/)
+- 可将 zip 解压到临时目录读取
+- 源码中无法确认的信息必须标记 [Manual Confirm]
+- 必须标注证据来源（哪个文件/哪段代码）
+- 禁止使用 Figma MCP、浏览器运行态、figma.site、截图或纯 Design 文件补充信息
+
+## 验收标准
+### 产物完整性
+- 产物结构完整、章节齐全
+- 每条信息有源码出处
+- 缺失信息标记 [Manual Confirm]
+
+{{#if degraded}}
+**注意**: 当前无专用模板，请按通用提取产物结构输出。
+{{/if}}
+`);
+// 4. read_only_analysis_prompt: 只读分析，默认不写文件
+const READ_ONLY_ANALYSIS_TEMPLATE = Handlebars.compile(`## 任务
+{{intent}}
+
+## 项目上下文
+- 技术栈: {{tech_stack}}
+- 产品类型: {{product_profile}}
+
+{{#if matched_knowledge}}
+## 适用知识
+{{#each matched_knowledge}}
+### {{this.name}}
+{{this.content}}
+
+{{/each}}
+{{/if}}
+
+## 约束
+- 默认不允许修改业务源码
+- 只读分析当前项目或指定材料
+- 输出结论、证据、风险和建议
+- 默认不写文件，除非明确指定输出路径
+
+{{#if output_artifact}}
+## 输出要求
+- 输出路径: {{output_artifact.path}}
+{{/if}}
+
+## 分析要求
+- 给出明确结论
+- 列出支撑证据
+- 标注风险和假设
+- 给出建议（如有）
+`);
+// 5. verification_only_prompt: 验证命令生成，不修改源码
+const VERIFICATION_ONLY_TEMPLATE = Handlebars.compile(`## 任务
+{{intent}}
+
+## 验证目标
+{{#if relevant_files}}
+### 相关文件
+{{#each relevant_files}}
+- {{this.path}} ({{this.reason}})
+{{/each}}
+{{/if}}
+
+## 约束
+- 默认不允许修改业务源码
+- 只生成验证命令和检查逻辑
+- 输出验证结果（通过/失败/需人工确认）
+
+## 验证要求
+- 列出具体验证命令
+- 标注预期结果
+- 标注不确定项
+`);
+// 6. direct_answer_prompt: 直接回答，不进入代码执行
+const DIRECT_ANSWER_TEMPLATE = Handlebars.compile(`## 任务
+{{intent}}
+
+## 要求
+- 直接回答用户问题
+- 不修改任何项目文件
+- 给出明确结论和依据
+`);
+/** 保留旧模板名为 CODE_EXECUTION_TEMPLATE 的别名（兼容旧测试） */
+const PROMPT_TEMPLATE = CODE_EXECUTION_TEMPLATE;
+/** 将 PromptInjectionPlan 渲染为 Markdown 段落（统一注入，避免模板内重复） */
+function renderPromptInjectionPlan(plan) {
+    const sections = [];
+    if (plan.evidence_refs.length > 0) {
+        sections.push("## 材料证据引用\n" + plan.evidence_refs.map((r) => "- " + r).join("\n"));
+    }
+    if (plan.required_summary.length > 0) {
+        sections.push("## 必需材料摘要\n" + plan.required_summary.map((s) => "- " + s).join("\n"));
+    }
+    if (plan.forbidden_notes.length > 0) {
+        sections.push("## 禁止/不可用材料\n" + plan.forbidden_notes.map((n) => "- " + n).join("\n"));
+    }
+    if (plan.manual_confirm_list.length > 0) {
+        sections.push("## 人工确认项\n" + plan.manual_confirm_list.map((c) => "- " + c).join("\n"));
+    }
+    if (plan.allowed_sources.length > 0) {
+        sections.push("## 允许的材料来源\n" + plan.allowed_sources.map((s) => "- " + s).join("\n"));
+    }
+    if (plan.forbidden_sources.length > 0) {
+        sections.push("## 禁止的材料来源\n" + plan.forbidden_sources.map((s) => "- " + s).join("\n"));
+    }
+    return sections.length > 0 ? "---\n\n" + sections.join("\n\n") : "";
+}
+/**
+ * 根据执行形态选择 prompt 模板。
+ */
+function chooseTemplate(templateName) {
+    switch (templateName) {
+        case "single_artifact_prompt": return SINGLE_ARTIFACT_TEMPLATE;
+        case "source_extraction_prompt": return SOURCE_EXTRACTION_TEMPLATE;
+        case "read_only_analysis_prompt": return READ_ONLY_ANALYSIS_TEMPLATE;
+        case "verification_only_prompt": return VERIFICATION_ONLY_TEMPLATE;
+        case "direct_answer_prompt": return DIRECT_ANSWER_TEMPLATE;
+        case "code_execution_prompt":
+        default: return CODE_EXECUTION_TEMPLATE;
+    }
+}
+/**
+ * 解析澄清答案，将路径注入 route_decision.input_materials，
+ * 清除已解决的 missing_required_inputs。
+ * 返回新的 route_decision（不修改原对象）。
+ */
+function resolveClarificationAnswers(decision, intent, answers) {
+    const resolved = {
+        ...decision,
+        input_materials: decision.input_materials.map((m) => ({ ...m })),
+        missing_required_inputs: [...decision.missing_required_inputs],
+    };
+    const addedPaths = [];
+    for (const answer of answers) {
+        // 提取路径 - absolute paths starting with /
+        const absPathPattern = /(?<![^\s])\/[^\s\]]+/g;
+        for (const m of answer.matchAll(absPathPattern)) {
+            const p = m[0];
+            if (p && p.length > 1 && !addedPaths.includes(p)) {
+                addedPaths.push(p);
+            }
+        }
+        // 提取相对路径 (word/word.ext 模式)
+        const relPathPattern = /[\w][\w.\-]*(?:\/[\w.\-]+)+\.[\w]+/g;
+        for (const m of answer.matchAll(relPathPattern)) {
+            const p = m[0];
+            if (p && !addedPaths.includes(p) && !addedPaths.some((ap) => ap.endsWith("/" + p))) {
+                addedPaths.push(p);
+            }
+        }
+    }
+    for (const p of addedPaths) {
+        if (resolved.input_materials.some((m) => m.path === p))
+            continue;
+        let kind = "file";
+        if (/\.(zip|tar\.gz|gz|rar|7z|jar|war)$/i.test(p))
+            kind = "archive";
+        else if (/\.log$/i.test(p))
+            kind = "log";
+        else if (/\.(md|txt|doc|pdf|docx)$/i.test(p))
+            kind = "doc";
+        else if (/\.(java|py|ts|tsx|js|jsx|go|rs)$/i.test(p))
+            kind = "file";
+        resolved.input_materials.push({ kind, path: p, required: true });
+    }
+    // 仅清除路径类型的缺失输入（保留非路径问题如"哪个框架?"）
+    if (addedPaths.length > 0) {
+        resolved.missing_required_inputs = resolved.missing_required_inputs.filter((m) => !/path|路径|目录|文件|folder|directory|file/i.test(m));
+    }
+    return resolved;
+}
+/**
+ * 获取 sf_expand 契约的 next_allowed_tools 和 forbidden_tools。
+ */
+function getExpandContractTools() {
+    const contract = findToolInvocationContractByName("sf_expand");
+    return {
+        next_allowed_tools: contract?.default_next_tools ?? [],
+        forbidden_tools: contract?.forbidden_next_tools ?? [],
+    };
+}
 /**
  * 将分类结果扩展为完整的 AI 执行 prompt 和配套元数据。
- * @param input - 膨胀输入，包含意图、分类结果、项目配置、知识索引等
- * @returns 膨胀结果，包含 prompt / scope / 验收标准 / 执行契约 / 不确定性触发条件
  */
 export async function expand(input) {
+    console.error("[soloForge] 意图膨胀: 开始扩展，路由=%s", input.route_decision?.route ?? input.classification?.task_type ?? "unknown");
     const { intent, classification, projectPath, config, knowledgeIndex } = input;
-    // 1. 查询知识库
+    let routeDecision = input.route_decision ?? classification.route_decision;
+    const templateName = routeDecision ? selectPromptTemplate(routeDecision) : "code_execution_prompt";
+    // 配置优先级解析 — 使用共享函数
+    let configResolution;
+    try {
+        configResolution = await resolveCurrentProjectConfigReports(projectPath);
+    }
+    catch (e) {
+        console.error("[soloForge] 意图扩展: 配置优先级解析失败 —", e);
+        configResolution = { reports: [], resolutions: [], warnings: [], entries: [] };
+    }
+    const configWarnings = configResolution.warnings;
+    // 消费澄清答案：解析路径，更新 input_materials，清除已解决的 missing_required_inputs
+    if (input.clarificationAnswers && input.clarificationAnswers.length > 0 && routeDecision) {
+        routeDecision = resolveClarificationAnswers(routeDecision, intent, input.clarificationAnswers);
+    }
+    // ── Privacy gate— 提前到所有 early-return 之前 ──
+    const privacyGate = evaluatePrivacyGate({
+        intent,
+        input_materials: input.route_decision?.input_materials?.map((m) => ({ path_or_ref: m.path ?? "" })) ?? [],
+    });
+    const safeIntent = privacyGate.redacted_text ?? redactSensitiveText(intent, "intent").redacted;
+    const safeGoal = redactSensitiveText(intent.slice(0, 200), "intent_goal").redacted;
+    // 提前创建产物记录 (在所有 early-return 之前)，确保所有路径都携带它
+    // task_id 为必需 — block if missing
+    let outputArtifactRecord;
+    if (routeDecision?.output_artifact && routeDecision.execution_shape !== "none" && routeDecision.execution_shape !== "code_execution") {
+        const artifactKind = mapToArtifactKind(routeDecision.output_artifact.kind);
+        if (!input.task_id) {
+            // task_id 缺失时始终阻止 for artifact routes
+            return {
+                task_id: "",
+                prompt: `## 阻塞：产物缺少 task_id\n\n任务: ${safeIntent}\n\nexpand() 收到 task_id 为空，无法创建产物记录。`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [],
+                matched_knowledge: [],
+                is_legacy_code: false,
+                degraded: true,
+                contract: {
+                    goal: safeGoal,
+                    scope: [],
+                    constraints: ["task_id 缺失"],
+                    verification: [],
+                    stop_conditions: ["task_id 缺失"],
+                },
+            };
+        }
+        // 收集源材料引用 from routeDecision.input_materials
+        const sourceMaterialRefs = routeDecision.input_materials
+            .filter((m) => m.path)
+            .map((m) => m.path);
+        // 冲突时拒绝 with input.task_id
+        if (routeDecision.output_artifact.taskId && routeDecision.output_artifact.taskId !== input.task_id) {
+            return {
+                task_id: input.task_id,
+                prompt: `## Contract Error: task_id 不一致\n\nrouteDecision.taskId=${routeDecision.output_artifact.taskId} !== input.task_id=${input.task_id}`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [], matched_knowledge: [],
+                is_legacy_code: false, degraded: true,
+                contract: { goal: safeGoal, scope: [], constraints: ["task_id 不一致"], verification: [], stop_conditions: ["task_id 不一致"] },
+            };
+        }
+        // 路径始终使用 input.task_id
+        outputArtifactRecord = createOutputArtifact({
+            kind: artifactKind,
+            task_id: input.task_id,
+            workflow_id: "pending",
+            created_by: "intent_expander",
+            path: getDefaultArtifactPath(artifactKind, input.task_id),
+            source_material_refs: sourceMaterialRefs,
+        });
+    }
+    // ── 工作流契约解析 ──
+    let workflowContract = undefined;
+    let workflowGovernanceFindings = [];
+    if (routeDecision) {
+        workflowContract = resolveWorkflow(routeDecision);
+        // 提前绑定 workflow_id to artifact record
+        if (workflowContract && outputArtifactRecord) {
+            outputArtifactRecord.workflow_id = workflowContract.id;
+        }
+        console.error("[soloForge] 意图膨胀: 工作流契约已解析，workflow=%s", workflowContract?.id ?? "none");
+        if (!workflowContract) {
+            return {
+                task_id: "",
+                prompt: `## 阻塞：无工作流契约\n\n任务: ${safeIntent}\n\nroute="${routeDecision.route}" + execution_shape="${routeDecision.execution_shape}" 没有匹配的工作流契约。\n\n请检查意图路由配置。`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [],
+                matched_knowledge: [],
+                is_legacy_code: false,
+                degraded: true,
+                workflow_trace: {
+                    workflow_id: "none",
+                    route: routeDecision.route,
+                    execution_shape: routeDecision.execution_shape,
+                    mutation_allowed: routeDecision.mutation_allowed,
+                    required_mechanisms: [],
+                    governance_findings: [{ severity: "hard_fail", rule: "gc-no-workflow", message: `no workflow contract for ${routeDecision.route}+${routeDecision.execution_shape}` }],
+                    degraded: true,
+                    state_transition_target: "none",
+                },
+                contract: {
+                    goal: safeGoal,
+                    scope: [],
+                    constraints: ["无工作流契约"],
+                    verification: [],
+                    stop_conditions: ["无工作流契约"],
+                },
+                output_artifact_record: outputArtifactRecord,
+            };
+        }
+        // mutation_allowed 一致性检查
+        if (workflowContract.mutation_allowed !== routeDecision.mutation_allowed) {
+            return {
+                task_id: "",
+                prompt: `## 阻塞：mutation_allowed 不一致\n\n任务: ${safeIntent}\n\n工作流 "${workflowContract.id}" 的 mutation_allowed=${workflowContract.mutation_allowed} 与 route_decision 的 mutation_allowed=${routeDecision.mutation_allowed} 不一致。`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [],
+                matched_knowledge: [],
+                is_legacy_code: false,
+                degraded: true,
+                workflow_trace: {
+                    workflow_id: workflowContract.id,
+                    route: routeDecision.route,
+                    execution_shape: routeDecision.execution_shape,
+                    mutation_allowed: workflowContract.mutation_allowed,
+                    required_mechanisms: workflowContract.required_mechanisms,
+                    governance_findings: [{ severity: "hard_fail", rule: "gc-mutation-mismatch", message: `mutation_allowed mismatch: workflow=${workflowContract.mutation_allowed} route=${routeDecision.mutation_allowed}` }],
+                    degraded: true,
+                    state_transition_target: "none",
+                },
+                contract: {
+                    goal: safeGoal,
+                    scope: [],
+                    constraints: ["mutation_allowed 不一致"],
+                    verification: [],
+                    stop_conditions: ["mutation_allowed 不一致"],
+                },
+                output_artifact_record: outputArtifactRecord,
+            };
+        }
+        // prompt_template 一致性检查
+        if (workflowContract.prompt_template !== templateName) {
+            return {
+                task_id: "",
+                prompt: `## 阻塞：prompt_template 不一致\n\n任务: ${safeIntent}\n\n工作流 "${workflowContract.id}" 要求 prompt_template="${workflowContract.prompt_template}"，但 selectPromptTemplate 返回 "${templateName}"。`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [],
+                matched_knowledge: [],
+                is_legacy_code: false,
+                degraded: true,
+                workflow_trace: {
+                    workflow_id: workflowContract.id,
+                    route: routeDecision.route,
+                    execution_shape: routeDecision.execution_shape,
+                    mutation_allowed: workflowContract.mutation_allowed,
+                    required_mechanisms: workflowContract.required_mechanisms,
+                    governance_findings: [{ severity: "hard_fail", rule: "gc-prompt-template-mismatch", message: `prompt_template mismatch: workflow="${workflowContract.prompt_template}" selected="${templateName}"` }],
+                    degraded: true,
+                    state_transition_target: "none",
+                },
+                contract: {
+                    goal: safeGoal,
+                    scope: [],
+                    constraints: ["prompt_template 不一致"],
+                    verification: [],
+                    stop_conditions: ["prompt_template 不一致"],
+                },
+            };
+        }
+    }
+    // 缺少必需输入时返回澄清，不生成执行 prompt（在 workflow resolution 之后）
+    if (routeDecision && routeDecision.missing_required_inputs.length > 0) {
+        console.error("[soloForge] 意图膨胀: 缺少必需输入 %d 项，返回澄清请求", routeDecision.missing_required_inputs.length);
+        return buildClarificationResult(intent, routeDecision, config, workflowContract, safeIntent, safeGoal);
+    }
+    // ── 输入材料契约 ──
+    let inputMaterials;
+    let ingestionEvidences;
+    let promptInjectionPlan;
+    const contractNotes = [];
+    if (routeDecision && routeDecision.input_materials.length > 0) {
+        const pathMaterials = routeDecision.input_materials.filter((m) => m.path);
+        if (pathMaterials.length > 0) {
+            const materials = pathMaterials.map((m) => createInputMaterial({ path_or_ref: m.path }));
+            inputMaterials = materials;
+            ingestionEvidences = materials.map((m) => createIngestionEvidence(m));
+            for (const m of materials) {
+                if (m.access_mode === "forbidden") {
+                    contractNotes.push(`[FORBIDDEN] ${m.path_or_ref}: 禁止读取`);
+                }
+                else if (m.trust_level === "external_unverified" || m.trust_level === "derived" || m.trust_level === "ai_generated") {
+                    contractNotes.push(`[Manual Confirm] ${m.path_or_ref}: 信任等级=${m.trust_level}`);
+                }
+            }
+            promptInjectionPlan = buildPromptInjectionPlan(materials, ingestionEvidences);
+        }
+    }
+    // ── 输入材料硬阻断──
+    if (inputMaterials) {
+        const forbiddenMaterials = inputMaterials.filter((m) => m.access_mode === "forbidden");
+        if (forbiddenMaterials.length > 0) {
+            const forbiddenPaths = forbiddenMaterials.map((m) => m.path_or_ref).join(", ");
+            console.error("[soloForge] 意图膨胀: 输入材料禁止读取: %s", forbiddenPaths);
+            return {
+                task_id: "",
+                prompt: `## 阻塞：输入材料禁止读取\n\n任务: ${safeIntent}\n\n以下材料路径触发禁止规则，不得读取:\n${forbiddenMaterials.map((m) => "  - " + m.path_or_ref).join("\\n")}\n\n请移除这些材料后重新调用。`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [],
+                matched_knowledge: [],
+                is_legacy_code: false,
+                degraded: true,
+                input_materials: inputMaterials,
+                ingestion_evidences: ingestionEvidences,
+                prompt_injection_plan: promptInjectionPlan,
+                contract: {
+                    goal: safeGoal,
+                    scope: [],
+                    constraints: ["输入材料包含禁止路径"],
+                    verification: [],
+                    stop_conditions: [],
+                },
+                output_artifact_record: outputArtifactRecord,
+                workflow_trace: workflowContract ? {
+                    workflow_id: workflowContract.id,
+                    route: routeDecision.route,
+                    execution_shape: routeDecision.execution_shape,
+                    mutation_allowed: workflowContract.mutation_allowed,
+                    required_mechanisms: workflowContract.required_mechanisms,
+                    governance_findings: [{ severity: "hard_fail", rule: "gc-forbidden-material", message: `材料禁止读取: ${forbiddenPaths}` }],
+                    degraded: true,
+                    state_transition_target: "none",
+                } : undefined,
+            };
+        }
+        const confirmations = input.input_material_confirmations ?? [];
+        const requiresConfirmationMaterials = inputMaterials.filter((m) => m.access_mode !== "forbidden"
+            && classifyIngestionStatus(m.path_or_ref) === "requires_confirmation"
+            && !confirmations.includes(m.path_or_ref));
+        if (requiresConfirmationMaterials.length > 0) {
+            const confirmPaths = requiresConfirmationMaterials.map((m) => m.path_or_ref);
+            return {
+                task_id: "",
+                prompt: `## 澄清请求\n\n任务: ${safeIntent}\n\n以下输入材料需要人工确认后才能使用:\n${confirmPaths.map((p) => "  - " + p).join("\\n")}\n\n请确认以上材料安全性后，通过 input_material_confirmations 参数重新调用。`,
+                scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+                acceptance: { automated: [], manual: [] },
+                matched_patterns: [],
+                matched_knowledge: [],
+                is_legacy_code: false,
+                degraded: true,
+                input_materials: inputMaterials,
+                ingestion_evidences: ingestionEvidences,
+                prompt_injection_plan: promptInjectionPlan,
+                contract: {
+                    goal: safeGoal,
+                    scope: [],
+                    constraints: ["输入材料需要确认"],
+                    verification: [],
+                    stop_conditions: [],
+                },
+                output_artifact_record: outputArtifactRecord,
+                workflow_trace: workflowContract ? {
+                    workflow_id: workflowContract.id,
+                    route: routeDecision.route,
+                    execution_shape: routeDecision.execution_shape,
+                    mutation_allowed: workflowContract.mutation_allowed,
+                    required_mechanisms: workflowContract.required_mechanisms,
+                    governance_findings: [],
+                    degraded: true,
+                    state_transition_target: "clarifying",
+                } : undefined,
+            };
+        }
+    }
+    // ── 隐私硬阻断门禁 (privacyGate 已在顶部计算) ──
+    const privacyLabels = privacyGate.labels;
+    const privacyRedactions = privacyGate.redaction_records;
+    const privacyFindings = privacyGate.findings;
+    // 硬阻断: 意图或输入材料中包含密钥/凭证
+    if (privacyGate.hard_fail) {
+        console.error("[soloForge] 意图膨胀: 隐私策略阻断，包含 %d 个禁止来源", privacyGate.blocked_sources.length);
+        return {
+            task_id: "",
+            prompt: [
+                "## 阻塞：隐私/敏感信息策略",
+                "",
+                "任务内容已因隐私策略脱敏",
+                "",
+                "隐私门禁触发 hard_fail，以下来源包含禁止级别的敏感信息:",
+                ...privacyGate.blocked_sources.map((s) => "  - " + s),
+                "",
+                "治理发现:",
+                ...privacyGate.findings.map((f) => `  [${f.severity}] ${f.rule}: ${f.message}`),
+                "",
+                "请移除敏感信息后重新调用。",
+            ].join("\n"),
+            scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+            acceptance: { automated: [], manual: [] },
+            matched_patterns: [],
+            matched_knowledge: [],
+            is_legacy_code: false,
+            degraded: true,
+            sensitivity_labels: privacyLabels.length > 0 ? privacyLabels : undefined,
+            redaction_records: privacyRedactions.length > 0 ? privacyRedactions : undefined,
+            privacy_findings: privacyFindings.length > 0 ? privacyFindings : undefined,
+            contract: {
+                goal: safeGoal,
+                scope: [],
+                constraints: ["隐私/敏感信息策略阻断"],
+                verification: [],
+                stop_conditions: ["隐私/敏感信息策略阻断"],
+            },
+            input_materials: inputMaterials,
+            ingestion_evidences: ingestionEvidences,
+            prompt_injection_plan: promptInjectionPlan,
+            output_artifact_record: outputArtifactRecord,
+            workflow_trace: workflowContract ? {
+                workflow_id: workflowContract.id,
+                route: routeDecision.route,
+                execution_shape: routeDecision.execution_shape,
+                mutation_allowed: workflowContract.mutation_allowed,
+                required_mechanisms: workflowContract.required_mechanisms,
+                governance_findings: privacyFindings.map((f) => ({ severity: f.severity, rule: f.rule, message: f.message })),
+                degraded: true,
+                state_transition_target: "none",
+            } : undefined,
+        };
+    }
+    // 1. 查询知识库（路由驱动匹配）
     const scopeFilters = classification.affected_repos.length > 0
         ? classification.affected_repos
         : ["shared"];
-    // 分级运行: quick_fix 模式减少知识匹配量以控制 Token 成本
     const knowledgeLimit = classification.strategy === "quick_fix" ? 2 : 5;
     const skipHeavyAnalysis = classification.strategy === "quick_fix";
-    const matchedEntries = knowledgeIndex.query({
-        scope: scopeFilters,
-        products: [config.product_profile],
-        keywords: extractKeywords(intent),
-        limit: knowledgeLimit,
-    });
-    // 记录知识使用
-    if (matchedEntries.length > 0) {
-        knowledgeIndex.markUsed(matchedEntries.map((e) => e.id));
+    const matchedEntries = queryKnowledgeForRoute(knowledgeIndex, intent, scopeFilters, config, routeDecision, knowledgeLimit);
+    // 知识注入边界（ 三道门过滤）
+    const productFilters = [config.product_profile];
+    const injectionReport = enforceKnowledgeInjectionBoundary(matchedEntries, routeDecision, scopeFilters, undefined, knowledgeLimit, productFilters);
+    const injectedIds = new Set(getInjectedEntryIds(injectionReport));
+    const filteredEntries = matchedEntries.filter((e) => injectedIds.has(e.id));
+    if (filteredEntries.length > 0) {
+        knowledgeIndex.markUsed(filteredEntries.map((e) => e.id));
+    }
+    // 治理校验：validateInjectionReport
+    const governanceFindings = validateInjectionReport(injectionReport);
+    const hardFails = governanceFindings.filter((f) => f.severity === "hard_fail");
+    const hasMissingRequiredKnowledge = injectionReport.missing_required_knowledge && injectionReport.missing_required_knowledge.length > 0;
+    // 存储治理发现 in report
+    injectionReport.governance_findings = governanceFindings;
+    const degraded = filteredEntries.length === 0 && injectionReport.injected_required.length === 0;
+    // 任何 hard_fail 都阻止 from validateInjectionReport — not just missing_required_knowledge
+    if (hardFails.length > 0) {
+        console.error("[soloForge] 意图膨胀: 注入校验失败，%d 个 hard_fail", hardFails.length);
+        const failMessages = hardFails.map((f) => f.message).join("\n");
+        const missingDesc = hasMissingRequiredKnowledge
+            ? injectionReport.missing_required_knowledge.map((m) => m.reason).join("\n")
+            : "";
+        const missingSection = missingDesc ? `\n\n缺少的必需知识:\n${missingDesc}` : "";
+        return {
+            task_id: "",
+            prompt: `## 阻塞：注入校验失败\n\n任务: ${safeIntent}\n\n以下硬性校验未通过:\n${failMessages}${missingSection}\n\n请修正后重新调用。`,
+            scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+            acceptance: { automated: [], manual: [] },
+            matched_patterns: [],
+            matched_knowledge: [],
+            is_legacy_code: false,
+            degraded: true,
+            injection_report: injectionReport,
+            input_materials: inputMaterials,
+            ingestion_evidences: ingestionEvidences,
+            prompt_injection_plan: promptInjectionPlan,
+            contract: {
+                goal: safeGoal,
+                scope: [],
+                constraints: ["注入校验失败，等待修正"],
+                verification: [],
+                stop_conditions: ["注入校验失败"],
+            },
+            output_artifact_record: outputArtifactRecord,
+            workflow_trace: workflowContract ? {
+                workflow_id: workflowContract.id,
+                route: routeDecision?.route ?? "",
+                execution_shape: routeDecision?.execution_shape ?? "",
+                mutation_allowed: workflowContract.mutation_allowed,
+                required_mechanisms: workflowContract.required_mechanisms,
+                governance_findings: workflowGovernanceFindings,
+                degraded: true,
+                state_transition_target: "none",
+            } : undefined,
+        };
     }
-    const degraded = matchedEntries.length === 0;
-    // 2. 检测遗留惯例（quick_fix 跳过以节省 Token）
+    // 2. 检测遗留惯例（只对 code_execution 执行）
     const legacyConventions = [];
     let isLegacyCode = false;
-    if (!skipHeavyAnalysis && !degraded && classification.affected_repos.length > 0) {
+    if (templateName === "code_execution_prompt" && !skipHeavyAnalysis && !degraded && classification.affected_repos.length > 0) {
         try {
             const repoDirs = classification.affected_repos
                 .map((r) => config.repos.find((repo) => repo.name === r)?.path)
                 .filter(Boolean);
-            // 检查仓库中第一个已存在文件的惯例
             const conventions = await detectConventions(repoDirs.map((d) => `${d}/src`).slice(0, 3), projectPath, config.conventions_file);
             if (conventions.length > 0) {
                 isLegacyCode = true;
                 legacyConventions.push(...conventions.map((c) => c.convention));
             }
         }
-        catch {
+        catch (e) {
+            console.error("[soloForge] 意图扩展: 惯例检测失败 —", e);
             // 惯例检测为尽力而为
         }
     }
-    // 3. 确定 scope
-    const scope = resolveScope(config, classification, degraded);
+    // 3. 确定 scope（非代码任务使用简化 scope）
+    const scope = resolveScope(config, classification, degraded, routeDecision);
     // 4. 生成验收标准
-    const acceptance = generateAcceptance(intent, classification, matchedEntries, config, degraded);
+    const acceptance = generateAcceptance(intent, classification, filteredEntries, config, degraded, routeDecision);
     // 5. 组装 prompt
     const techStack = buildTechStackLabel(config);
-    let prompt = PROMPT_TEMPLATE({
-        intent,
-        tech_stack: techStack,
-        product_profile: config.product_profile,
-        affected_repos: classification.affected_repos.join(", "),
-        matched_knowledge: matchedEntries.map((e) => ({
-            name: e.name,
-            content: e.body || e.when,
-        })),
-        relevant_files: scope.allowed_paths.slice(0, 10).map((p) => ({ path: p, reason: "scope 允许路径" })),
-        is_legacy_code: isLegacyCode,
-        legacy_conventions: legacyConventions,
-        scope: {
-            allowed_paths: scope.allowed_paths.join(", "),
-            new_files_allowed: scope.new_files_allowed,
-            new_file_patterns: scope.new_file_patterns?.join(", "),
-        },
-        acceptance,
-        degraded,
-    });
-    // 5.1 注入计划阶段上下文（P1: AI 唯一执行者, P2: 模板是护栏, P3: 产物系统）
+    const template = chooseTemplate(templateName);
+    const templateData = buildTemplateData(safeIntent, techStack, config, classification, scope, filteredEntries, legacyConventions, isLegacyCode, acceptance, degraded, routeDecision);
+    if (promptInjectionPlan)
+        templateData.prompt_injection_plan = promptInjectionPlan;
+    // ── 双层机制模板注入（ 路由/状态过滤） ──
+    const dlMechanisms = listMechanismLayerMaps();
+    const currentRoute = routeDecision?.route ?? "";
+    const currentWorkflow = workflowContract?.id ?? "";
+    const dlRules = [];
+    for (const mech of dlMechanisms) {
+        // 仅 dual_layer_enforced or experimental_dual_layer mechanisms inject
+        if (mech.status !== "dual_layer_enforced" && mech.status !== "experimental_dual_layer")
+            continue;
+        // 路由必须匹配 mechanism's injected_routes
+        if (mech.injected_routes && mech.injected_routes.length > 0 && currentRoute) {
+            if (!mech.injected_routes.includes(currentRoute))
+                continue;
+        }
+        // 工作流必须匹配 mechanism's injected_workflows
+        if (mech.injected_workflows && mech.injected_workflows.length > 0 && currentWorkflow) {
+            if (!mech.injected_workflows.includes(currentWorkflow))
+                continue;
+        }
+        // 仅注入必需资产; supporting are handled by knowledge injection boundary
+        const requiredAssets = mech.template_assets.filter((ta) => ta.consumption_mode === "required");
+        for (const ra of requiredAssets) {
+            try {
+                const content = fss.readFileSync(ra.path, "utf-8").trim();
+                if (content)
+                    dlRules.push(`[${mech.mechanism_name}] ${content}`);
+            }
+            catch (e) {
+                console.error("[soloForge] 意图扩展: 双层机制模板加载失败 —", e);
+            }
+        }
+    }
+    if (dlRules.length > 0) {
+        templateData.dual_layer_rules = dlRules;
+        const existing = templateData.matched_knowledge;
+        if (existing) {
+            existing.push({ name: "强制机制规则（双层注入）", content: dlRules.join("\n\n") });
+        }
+    }
+    let prompt = template(templateData);
+    console.error("[soloForge] 意图膨胀: Prompt 模板渲染完成，模板=%s", templateName);
+    // 5.1 注入计划阶段上下文
     if (input.plan_context) {
         prompt = injectPlanContext(prompt, input.plan_context, knowledgeIndex);
     }
-    // 6. 使用计数已通过 markUsed 更新，无需重复递增
     // 7. 生成执行契约（能力 1）
-    const contract = buildExecutionContract(intent, classification, scope, acceptance);
+    const contract = buildExecutionContract(safeIntent, classification, scope, acceptance);
     // 8. 生成不确定性触发条件（quick_fix 跳过）
     const uncertaintyTriggers = skipHeavyAnalysis
         ? []
@@ -143,12 +853,12 @@ export async function expand(input) {
     const breakerResult = checkCircuitBreaker({
         intent,
         classification,
-        matchedEntries,
+        matchedEntries: filteredEntries,
         degraded,
     });
-    // 熔断触发时: 注入头脑风暴 prompt，不阻止流程但标记 tripped
     let circuitBreakerOutput;
     if (breakerResult.tripped) {
+        console.error("[soloForge] 意图膨胀: 意图熔断触发，置信度=%.2f", breakerResult.confidence);
         circuitBreakerOutput = breakerResult;
         prompt += `
 
@@ -167,38 +877,365 @@ ${breakerResult.brainstorm.blind_spots.map((s) => `- ${s}`).join("\n")}
 ### 【闭环逼问】
 ${breakerResult.brainstorm.decision_questions.map((q, i) => `${i + 1}. ${q.question}\n   A) ${q.option_a}\n   B) ${q.option_b}`).join("\n\n")}
 
-**注意**: 请等待人类决策后再输出执行代码。
+**注意**: ${routeDecision?.execution_shape === "code_execution"
+            ? "请等待人类决策后再输出执行代码。"
+            : "请先补齐阻塞输入，或在产物中标记 [Manual Confirm] 后再生成产物。"}
 `;
     }
+    const expandTools = getExpandContractTools();
+    if (contractNotes.length > 0) {
+        prompt += "\n\n---\n\n## 输入材料契约检查\n" + contractNotes.join("\n");
+    }
+    // 追加配置优先级警告 to prompt 
+    if (configWarnings.length > 0) {
+        prompt += "\n\n---\n\n## 配置优先级警告\n" + configWarnings.join("\n");
+    }
+    // 核心工程执行原则注入
+    const coreTaskLevel = getTaskLevel(routeDecision?.route, routeDecision?.execution_shape);
+    const coreRequiredPrinciples = getRequiredPrinciples(coreTaskLevel);
+    if (coreRequiredPrinciples.length > 0) {
+        const principleLines = listCorePrinciples()
+            .filter((p) => getEnforcementLevel(p.id, coreTaskLevel) !== "not_applicable")
+            .map((p) => {
+            const level = getEnforcementLevel(p.id, coreTaskLevel);
+            const tag = level === "required" ? "[REQUIRED]" : "[advisory]";
+            return `- **${tag} ${p.name} (${p.chinese_name})**: ${p.rule}`;
+        });
+        prompt += "\n\n---\n\n## 核心工程执行原则 (任务等级: " + coreTaskLevel + ")\n" + principleLines.join("\n");
+        prompt += "\n\n> 以上原则中 [REQUIRED] 为硬性要求，违反将导致验证失败。[advisory] 为建议性要求。";
+    }
+    // 注入 prompt_injection_plan 段落 into prompt (unified for all routes)
+    if (promptInjectionPlan) {
+        const rendered = renderPromptInjectionPlan(promptInjectionPlan);
+        if (rendered) {
+            prompt += "\n\n" + rendered;
+        }
+    }
+    // 用真实引用丰富产物 before returning
+    if (outputArtifactRecord) {
+        // 绑定知识引用 from matched knowledge entries
+        outputArtifactRecord.knowledge_refs = filteredEntries.map((e) => e.id);
+        // 绑定摄取证据引用
+        if (ingestionEvidences && ingestionEvidences.length > 0) {
+            outputArtifactRecord.evidence_refs = ingestionEvidences
+                .filter((ie) => ie.access_mode !== "forbidden")
+                .map((ie) => `ingestion:${ie.material_id}:${ie.source_ref}`);
+        }
+        // 解析 workflow_id from workflow contract
+        if (workflowContract) {
+            outputArtifactRecord.workflow_id = workflowContract.id;
+        }
+    }
+    console.error("[soloForge] 意图膨胀: 扩展完成，degraded=%s, 匹配知识=%d 条", degraded ? "true" : "false", filteredEntries.length);
     return {
-        task_id: "", // 由调用方填充
+        task_id: "",
         prompt,
         scope,
         acceptance,
-        matched_patterns: matchedEntries.map((e) => e.name),
-        matched_knowledge: matchedEntries.map((e) => e.name),
+        matched_patterns: filteredEntries.map((e) => e.name),
+        matched_knowledge: filteredEntries.map((e) => e.name),
+        injection_report: injectionReport,
         is_legacy_code: isLegacyCode,
         legacy_conventions: legacyConventions.length > 0 ? legacyConventions : undefined,
         degraded,
         contract,
         uncertainty_triggers: uncertaintyTriggers.length > 0 ? uncertaintyTriggers : undefined,
         circuit_breaker: circuitBreakerOutput,
+        next_allowed_tools: expandTools.next_allowed_tools,
+        forbidden_tools: expandTools.forbidden_tools,
+        input_materials: inputMaterials,
+        ingestion_evidences: ingestionEvidences,
+        prompt_injection_plan: promptInjectionPlan,
+        output_artifact_record: outputArtifactRecord,
+        sensitivity_labels: privacyLabels.length > 0 ? privacyLabels : undefined,
+        redaction_records: privacyRedactions.length > 0 ? privacyRedactions : undefined,
+        privacy_findings: privacyFindings.length > 0 ? privacyFindings : undefined,
+        config_resolution_reports: configResolution.reports.length > 0 ? configResolution.reports : undefined,
+        workflow_trace: workflowContract ? {
+            workflow_id: workflowContract.id,
+            route: routeDecision?.route ?? "",
+            execution_shape: routeDecision?.execution_shape ?? "",
+            mutation_allowed: workflowContract.mutation_allowed,
+            required_mechanisms: workflowContract.required_mechanisms,
+            governance_findings: workflowGovernanceFindings,
+            degraded,
+            state_transition_target: workflowContract.allowed_state_transitions[0] ?? "none",
+            checked_items: buildCheckedItems(workflowContract, routeDecision),
+        } : undefined,
+    };
+}
+function buildCheckedItems(contract, routeDecision) {
+    const items = [
+        "workflow_resolved",
+        "mutation_allowed_checked",
+        "prompt_template_checked",
+        "required_mechanisms_declared",
+    ];
+    if (routeDecision && !routeDecision.mutation_allowed) {
+        items.push("read_only_scope_checked");
+    }
+    return items;
+}
+/**
+ * 缺少必需输入时返回澄清结果（不生成执行 prompt）。
+ */
+function buildClarificationResult(intent, routeDecision, config, workflowContract, safeIntent, safeGoal) {
+    const clarification = routeDecision.missing_required_inputs.join("\n");
+    return {
+        task_id: "",
+        prompt: `## 澄清请求\n\n任务: ${safeIntent}\n\n缺少必需输入:\n${clarification}\n\n请补充以上信息后重新调用。`,
+        scope: { allowed_paths: [], readonly_paths: [], new_files_allowed: false },
+        acceptance: { automated: [], manual: [] },
+        matched_patterns: [],
+        matched_knowledge: [],
+        is_legacy_code: false,
+        degraded: true,
+        contract: {
+            goal: safeGoal,
+            scope: [],
+            constraints: ["缺少必需输入，等待澄清"],
+            verification: [],
+            stop_conditions: [],
+        },
+        workflow_trace: workflowContract ? {
+            workflow_id: workflowContract.id,
+            route: routeDecision.route,
+            execution_shape: routeDecision.execution_shape,
+            mutation_allowed: workflowContract.mutation_allowed,
+            required_mechanisms: workflowContract.required_mechanisms,
+            governance_findings: [],
+            degraded: true,
+            state_transition_target: "clarifying",
+        } : undefined,
+    };
+}
+/**
+ * 根据 pipeline_hint 名称加载内置流程模板。
+ */
+function loadBuiltinByPipeline(pipelineName) {
+    const entries = [];
+    // pipeline_hint 格式: source-prototype-to-delivery:step-1 → 找源码原型交付流程.md
+    const nameToTemplate = {
+        "source-prototype-to-delivery": "源码原型交付流程.md",
+    };
+    const templateFile = nameToTemplate[pipelineName];
+    if (templateFile) {
+        const entry = loadBuiltinTemplate(templateFile, "procedures");
+        if (entry)
+            entries.push(entry);
+    }
+    return entries;
+}
+/** 包内模板知识库根目录 */
+function getTemplatesRoot() {
+    const thisDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(thisDir, "..", "..", "templates", "knowledge");
+}
+/**
+ * 当知识索引中没有找到内置模板时，从 templates/knowledge/ 加载为 KnowledgeEntry。
+ * 只加载指定名称的文件。
+ */
+function loadBuiltinTemplate(fileName, subDir) {
+    const templatesRoot = getTemplatesRoot();
+    const safeName = path.basename(fileName); // basename 防止路径穿越
+    const filePath = path.join(templatesRoot, subDir, safeName);
+    try {
+        if (!fss.existsSync(filePath))
+            return null;
+        const raw = fss.readFileSync(filePath, "utf-8");
+        const { data, content: body } = matter(raw);
+        const name = data.name || path.basename(fileName, ".md");
+        const type = inferTypeFromSubDir(subDir);
+        return {
+            id: `builtin-${name}`,
+            file_path: filePath,
+            name,
+            type,
+            when: data.when || "",
+            body,
+            scope: data.scope || ["shared"],
+            products: data.products || ["*"],
+            tech_stack: data.tech_stack,
+            created_at: data.created_at || new Date().toISOString().split("T")[0],
+            updated_at: data.updated_at || new Date().toISOString().split("T")[0],
+            usage_count: 0,
+            confidence: data.confidence ?? 1.0,
+            status: "active",
+        };
+    }
+    catch (e) {
+        console.error("[soloForge] 意图扩展: 内置模板加载失败 —", e);
+        return null;
+    }
+}
+function inferTypeFromSubDir(subDir) {
+    if (subDir.includes("procedures"))
+        return "pipeline_procedure";
+    if (subDir.includes("acceptance_templates"))
+        return "acceptance_template";
+    if (subDir.includes("review_rules"))
+        return "review_rule";
+    if (subDir.includes("domain"))
+        return "domain";
+    return "pattern";
+}
+/**
+ * 路由驱动的知识匹配。
+ * 优先使用 pipeline_hint、output_artifact.kind、route + execution_shape，
+ * 降级为同类型通用产物 prompt，不退化成编码 prompt。
+ */
+function queryKnowledgeForRoute(knowledgeIndex, intent, scopeFilters, config, routeDecision, limit) {
+    if (!routeDecision) {
+        // 无 route_decision 时回退到旧逻辑
+        return knowledgeIndex.query({
+            scope: scopeFilters,
+            products: [config.product_profile],
+            keywords: extractKeywords(intent),
+            limit,
+        });
+    }
+    const seen = new Set();
+    const results = [];
+    function addEntries(entries) {
+        for (const e of entries) {
+            if (!seen.has(e.id)) {
+                seen.add(e.id);
+                results.push(e);
+            }
+        }
+    }
+    // 优先级 1: pipeline_hint 精确匹配（不提前 return）
+    if (routeDecision.pipeline_hint) {
+        const pipelineName = routeDecision.pipeline_hint.split(":")[0];
+        const pipelineResults = knowledgeIndex.query({
+            scope: scopeFilters,
+            products: [config.product_profile],
+            type: "pipeline_procedure",
+            keywords: extractKeywords(pipelineName),
+            limit: 3,
+        });
+        addEntries(pipelineResults);
+        // 内置模板回退: pipeline_hint 名称未命中时从 templates/knowledge/ 加载
+        if (pipelineResults.length === 0) {
+            const builtin = loadBuiltinByPipeline(pipelineName);
+            if (builtin)
+                addEntries(builtin);
+        }
+    }
+    // 优先级 2: output_artifact.kind 映射 acceptance_template（不提前 return）
+    if (routeDecision.output_artifact?.kind) {
+        // 先按 template 文件名精确匹配
+        const templateName = routeDecision.output_artifact.template;
+        if (templateName) {
+            const allTemplates = knowledgeIndex.query({
+                scope: scopeFilters,
+                products: [config.product_profile],
+                type: "acceptance_template",
+                keywords: [],
+                limit: 100,
+            });
+            const exactMatch = allTemplates.find((e) => matchesTemplateByName(e, templateName));
+            if (exactMatch)
+                addEntries([exactMatch]);
+            // 内置模板回退: template 名称未命中时从 templates/knowledge/acceptance_templates/ 加载
+            if (!exactMatch) {
+                const builtinTemplate = loadBuiltinTemplate(templateName, "acceptance_templates");
+                if (builtinTemplate)
+                    addEntries([builtinTemplate]);
+            }
+        }
+        // 再按 artifact kind 关键词匹配
+        const artifactKeywords = {
+            prototype_spec: ["原型", "prototype", "原型说明"],
+            api_spec: ["接口", "API", "接口设计"],
+            design_doc: ["设计", "架构", "详细设计"],
+            test_plan: ["测试", "测试计划"],
+            migration_plan: ["迁移", "迁移方案"],
+            review_report: ["审查", "review"],
+            task_breakdown: ["任务", "拆解"],
+            root_cause: ["根因", "分析"],
+            incident_review: ["故障", "复盘"],
+        };
+        const artifactKws = artifactKeywords[routeDecision.output_artifact.kind] ?? [];
+        if (artifactKws.length > 0) {
+            const templateResults = knowledgeIndex.query({
+                scope: scopeFilters,
+                products: [config.product_profile],
+                type: "acceptance_template",
+                keywords: artifactKws,
+                limit: 2,
+            });
+            addEntries(templateResults);
+        }
+    }
+    // 优先级 3: intent keywords 补充（填满 limit）
+    if (results.length < limit) {
+        const keywordResults = knowledgeIndex.query({
+            scope: scopeFilters,
+            products: [config.product_profile],
+            keywords: extractKeywords(intent),
+            limit: limit,
+        });
+        addEntries(keywordResults);
+    }
+    return results.slice(0, limit);
+}
+/**
+ * 根据执行形态构建模板数据。
+ */
+function buildTemplateData(intent, techStack, config, classification, scope, matchedEntries, legacyConventions, isLegacyCode, acceptance, degraded, routeDecision) {
+    const base = {
+        intent,
+        tech_stack: techStack,
+        product_profile: config.product_profile,
+        affected_repos: classification.affected_repos.join(", "),
+        matched_knowledge: matchedEntries.map((e) => ({
+            name: e.name,
+            content: e.body || e.when,
+        })),
+        relevant_files: scope.allowed_paths.slice(0, 10).map((p) => ({ path: p, reason: "scope 允许路径" })),
+        is_legacy_code: isLegacyCode,
+        legacy_conventions: legacyConventions,
+        scope: {
+            allowed_paths: scope.allowed_paths.join(", "),
+            new_files_allowed: scope.new_files_allowed,
+            new_file_patterns: scope.new_file_patterns?.join(", "),
+        },
+        acceptance,
+        degraded,
     };
+    if (routeDecision) {
+        base.output_artifact = routeDecision.output_artifact;
+        base.input_materials = routeDecision.input_materials;
+        // 根据 ingestion_status 构建 input_material_contract_notes
+        const contractTemplateNotes = [];
+        for (const m of routeDecision.input_materials) {
+            if (m.ingestion_status === "forbidden")
+                contractTemplateNotes.push("FORBIDDEN: " + (m.path ?? "") + " 禁止读取");
+            else if (m.ingestion_status === "requires_confirmation")
+                contractTemplateNotes.push("REQUIRES_CONFIRMATION: " + (m.path ?? "") + " 需确认");
+        }
+        base.input_material_contract_notes = contractTemplateNotes.length > 0 ? contractTemplateNotes : undefined;
+        base.pipeline_hint = routeDecision.pipeline_hint;
+    }
+    return base;
 }
 /**
- * P2（做什么/怎么做分离）+ P3（产物系统）：
- * 将当前计划步骤的上下文注入到 expansion prompt 中。
- * 包括：上一步产出文件内容、输出格式模板、建议工具。
- * AI 自主决定执行方式（P4: 评估结果不评估路径）。
- * @param prompt - 基础 prompt 文本
- * @param planContext - 当前计划步骤上下文
- * @param knowledgeIndex - 知识索引管理器，用于查询输出模板
- * @returns 注入上下文后的 prompt 文本
+ * 按模板文件名精确匹配知识条目。
+ * 匹配 entry.name、file basename (with/without extension)。
+ */
+function matchesTemplateByName(entry, templateName) {
+    const requested = templateName.trim();
+    const fileName = path.basename(entry.file_path);
+    const fileStem = path.basename(entry.file_path, path.extname(entry.file_path));
+    return [entry.name, fileName, fileStem].some((c) => c.trim() === requested);
+}
+/**
+ * 注入计划阶段上下文（P2 + P3）
  */
 function injectPlanContext(prompt, planContext, knowledgeIndex) {
     const { current_step, previous_outputs } = planContext;
     const sections = [];
-    // 上一步产出（P3: 产物系统，通过文件传递上下文）
     const prevEntries = Object.entries(previous_outputs);
     if (prevEntries.length > 0) {
         sections.push("## 前序阶段产出");
@@ -208,22 +1245,19 @@ function injectPlanContext(prompt, planContext, knowledgeIndex) {
             }
         }
     }
-    // 输出格式模板（P2: 模板是护栏不是笼子）
     if (current_step.output_template) {
         const templateEntries = knowledgeIndex.query({
             type: "acceptance_template",
             keywords: [],
         });
-        const matched = templateEntries.find((e) => e.name === current_step.output_template);
+        const matched = templateEntries.find((e) => matchesOutputTemplate(e, current_step.output_template));
         if (matched?.body) {
             sections.push(`## 输出格式参考（模板: ${current_step.output_template}）\n${matched.body}`);
         }
     }
-    // 输出路径（P3: 产出保存位置）
     if (current_step.output_path) {
         sections.push(`## 产出保存\n将本阶段产出写入: ${current_step.output_path}`);
     }
-    // 建议工具（P2: AI 自主决定是否使用）
     if (current_step.suggested_tools && current_step.suggested_tools.length > 0) {
         sections.push(`## 建议工具（可选）\n${current_step.suggested_tools.map((t) => `- ${t}`).join("\n")}`);
     }
@@ -231,26 +1265,49 @@ function injectPlanContext(prompt, planContext, knowledgeIndex) {
         return prompt;
     return `${prompt}\n\n---\n\n## 当前计划阶段\n正在执行: **${current_step.title}**\n${current_step.description}\n\n${sections.join("\n\n")}`;
 }
-/**
- * 简单关键词提取: 移除中文虚词后按分隔符拆分，过滤长度不足 2 的词。
- * @param intent - 原始意图文本
- * @returns 关键词数组
- */
+function matchesOutputTemplate(entry, outputTemplate) {
+    const requested = normalizeTemplateName(outputTemplate);
+    const fileName = path.basename(entry.file_path);
+    const fileStem = path.basename(entry.file_path, path.extname(entry.file_path));
+    return [
+        entry.name,
+        fileName,
+        fileStem,
+    ].some((candidate) => normalizeTemplateName(candidate) === requested);
+}
+function normalizeTemplateName(name) {
+    return name.trim();
+}
 function extractKeywords(intent) {
-    // 简单关键词提取: 按常见分隔符拆分，过滤短词
     return intent
         .replace(/[的了吗呢把被在从对和与或是]/g, " ")
         .split(/[\s,，、；;]+/)
         .filter((w) => w.length >= 2);
 }
 /**
- * 解析任务作用域: 基于分类结果的受影响仓库确定允许修改路径和只读路径。
- * @param config - 项目配置
- * @param classification - 分类结果
- * @param degraded - 是否处于降级模式（无知识匹配时降级，禁止新建文件）
- * @returns 作用域结果，包含 allowed_paths / readonly_paths / new_files_allowed
+ * 解析 scope: 非代码任务使用简化 scope。
  */
-function resolveScope(config, classification, degraded) {
+function resolveScope(config, classification, degraded, routeDecision) {
+    // 非代码任务: scope 仅允许 .soloforge/output/ 和产物路径
+    if (routeDecision && !routeDecision.mutation_allowed) {
+        const outputArtifact = routeDecision.output_artifact;
+        const allowedPaths = [];
+        if (outputArtifact?.path) {
+            // 只允许写产物路径所在的目录
+            const dir = outputArtifact.path.replace(/\/[^/]+$/, "");
+            allowedPaths.push(dir);
+        }
+        else {
+            allowedPaths.push(".soloforge/output/");
+        }
+        return {
+            allowed_paths: allowedPaths,
+            readonly_paths: config.repos.flatMap((r) => r.scope),
+            new_files_allowed: true,
+            new_file_patterns: ["*.md"],
+        };
+    }
+    // 代码修改任务: 原有逻辑
     const allowedPaths = [];
     for (const repoName of classification.affected_repos) {
         const repo = config.repos.find((r) => r.name === repoName);
@@ -258,12 +1315,10 @@ function resolveScope(config, classification, degraded) {
             allowedPaths.push(...repo.scope);
         }
     }
-    // 无匹配仓库或降级时回退到默认 scope
     if (allowedPaths.length === 0) {
         allowedPaths.push(...(config.scope.backend || []));
         allowedPaths.push(...(config.scope.frontend || []));
     }
-    // 计算 readonly_paths: 不在受影响仓库 scope 内但属于项目的路径
     const readonlyPaths = [];
     for (const repo of config.repos) {
         if (!classification.affected_repos.includes(repo.name)) {
@@ -275,24 +1330,46 @@ function resolveScope(config, classification, degraded) {
         readonly_paths: readonlyPaths,
         new_files_allowed: !degraded,
         new_file_patterns: !degraded && classification.strategy === "full_pipeline"
-            ? ["**/*"] // full_pipeline 模式下允许新建任意文件
+            ? ["**/*"]
             : undefined,
     };
 }
 /**
- * 生成验收标准: 降级模式仅含编译+测试，完整模式额外解析知识中的验收项并按任务类型添加人工验收。
- * @param intent - 用户意图
- * @param classification - 分类结果
- * @param matchedEntries - 匹配的知识条目
- * @param _config - 项目配置（预留参数）
- * @param degraded - 是否处于降级模式
- * @returns 自动验收项和人工验收项
+ * 生成验收标准: 根据执行形态选择不同验收。
  */
-function generateAcceptance(intent, classification, matchedEntries, _config, degraded) {
+function generateAcceptance(intent, classification, matchedEntries, _config, degraded, routeDecision) {
     const automated = [];
     const manual = [];
+    // 非代码任务: 产物验收而非编译/测试
+    if (routeDecision && routeDecision.execution_shape !== "code_execution") {
+        if (routeDecision.output_artifact?.path) {
+            automated.push({
+                id: "A-artifact-exists",
+                description: `产物文件已生成: ${routeDecision.output_artifact.path}`,
+                type: "automated",
+            });
+        }
+        automated.push({
+            id: "A-completeness",
+            description: "产物结构完整，无空白占位",
+            type: "automated",
+        });
+        manual.push({
+            id: "M-quality",
+            description: "产物质量满足可交接标准",
+            type: "manual",
+        });
+        // 从知识中解析验收项
+        for (const entry of matchedEntries) {
+            if (entry.body) {
+                const items = parseAcceptanceItems(entry.body);
+                automated.push(...items);
+            }
+        }
+        return { automated, manual };
+    }
+    // 代码修改任务: 原有逻辑
     if (degraded) {
-        // 降级模式: 仅基本验收（sf_verify 独立生成 build/test 命令，此处仅声明验收项）
         automated.push({
             id: "A-build",
             description: "编译通过，无类型错误",
@@ -305,20 +1382,17 @@ function generateAcceptance(intent, classification, matchedEntries, _config, deg
         });
         return { automated, manual };
     }
-    // 完整模式: 构建 + 模式特定 + 任务类型验收
     automated.push({
         id: "A-build",
         description: "编译通过，无类型错误",
         type: "automated",
     });
-    // 模式特定验收: 从知识正文中解析 ## 验收项
     for (const entry of matchedEntries) {
         if (entry.body) {
             const items = parseAcceptanceItems(entry.body);
             automated.push(...items);
         }
     }
-    // 任务类型特定的人工验收项
     if (classification.task_type === "feature") {
         manual.push({
             id: "M-ux",
@@ -335,12 +1409,6 @@ function generateAcceptance(intent, classification, matchedEntries, _config, deg
     }
     return { automated, manual };
 }
-/**
- * 从知识条目的 Markdown 正文中解析 "## 验收项" 下的验收条目。
- * 支持 `(check: 命令)` 语法提取自动检查命令。
- * @param body - 知识条目的 Markdown 正文
- * @returns 解析到的验收项数组
- */
 function parseAcceptanceItems(body) {
     const items = [];
     if (!body.includes("## 验收项"))
@@ -355,7 +1423,6 @@ function parseAcceptanceItems(body) {
         if (inSection && line.startsWith("## "))
             break;
         if (inSection) {
-            // 支持 (check: ...) 提取 check_command
             const match = line.match(/- \[([A-Z]+-\d+)\]\s*(.+?)(?:\s*\(check:\s*(.+)\))?$/);
             if (match) {
                 const item = { id: match[1], description: match[2].trim(), type: "automated" };
@@ -367,11 +1434,6 @@ function parseAcceptanceItems(body) {
     }
     return items;
 }
-/**
- * 构建技术栈标签字符串，用于 prompt 中展示项目技术栈信息。
- * @param config - 项目配置
- * @returns 技术栈标签，如 "spring-boot 3.x + react 18"
- */
 function buildTechStackLabel(config) {
     const parts = [];
     if (config.tech_stack.backend.framework) {
@@ -383,19 +1445,9 @@ function buildTechStackLabel(config) {
     return parts.join(" + ") || "未知";
 }
 // ── 能力 1: 执行契约 ──
-/**
- * 构建执行契约: 根据风险和复杂度生成约束条件和停止条件。
- * 高风险任务收紧约束并限制修复循环次数。
- * @param intent - 用户意图
- * @param classification - 分类结果
- * @param scope - 作用域
- * @param acceptance - 验收标准
- * @returns 执行契约
- */
 function buildExecutionContract(intent, classification, scope, acceptance) {
     const constraints = [];
     const stopConditions = [];
-    // 按 risk 级别收紧约束
     if (classification.risk === "high") {
         constraints.push("高风险任务：每个变更文件必须有明确来源（任务卡/缺陷/设计锚点）");
         constraints.push("禁止顺手重构或范围外变更");
@@ -423,8 +1475,6 @@ function buildExecutionContract(intent, classification, scope, acceptance) {
     };
 }
 // ── 能力 4: 不确定性协议 ──
-// 不确定性模式表: 识别高风险领域（DDL 变更、权限、金额、跨系统、状态机、破坏性操作、并发、敏感数据）
-// 每个模式包含: 正则匹配、触发类型、描述、选项及权衡、推荐方案
 const UNCERTAINTY_PATTERNS = [
     {
         pattern: /(?:表结构|DDL|加字段|删字段|改字段|索引|migration)/i,
@@ -507,13 +1557,6 @@ const UNCERTAINTY_PATTERNS = [
         recommendation: "传输+存储均加密",
     },
 ];
-/**
- * 根据意图文本和分类结果生成不确定性触发条件。
- * 高风险 + 高歧义时额外追加确认触发。
- * @param classification - 分类结果
- * @param intent - 用户意图文本
- * @returns 匹配到的不确定性触发条件数组
- */
 function buildUncertaintyTriggers(classification, intent) {
     const triggers = [];
     for (const pattern of UNCERTAINTY_PATTERNS) {
@@ -526,7 +1569,6 @@ function buildUncertaintyTriggers(classification, intent) {
             });
         }
     }
-    // 高风险 + 高歧义 = 额外确认
     if (classification.risk === "high" && classification.ambiguity === "high") {
         triggers.push({
             trigger_type: "high_risk_high_ambiguity",
@@ -540,31 +1582,27 @@ function buildUncertaintyTriggers(classification, intent) {
     }
     return triggers;
 }
-/** 熔断置信度阈值: 低于此值禁止输出执行代码 */
 const CONFIDENCE_THRESHOLD = 0.95;
 /**
- * 置信度熔断器 — 评估意图清晰度，低于阈值触发 sf_brainstorm 模式。
- * 评估维度: 知识匹配度、意图明确性、分类一致性。
- * 熔断后不输出执行代码，而是输出头脑风暴结构供人类决策。
+ * 意图熔断器 — 评估意图理解置信度，低于阈值时触发熔断并生成头脑风暴辅助决策。
+ * @param params - 熔断器参数，包含意图、分类结果、匹配知识条目和降级标记
+ * @returns 熔断结果，包含是否触发、置信度、原因和头脑风暴输出
  */
 export function checkCircuitBreaker(params) {
     const { intent, classification, matchedEntries, degraded } = params;
     let confidence = 1.0;
-    // 维度 1: 知识匹配度（权重 0.35）
     if (degraded || matchedEntries.length === 0) {
         confidence -= 0.35;
     }
     else if (matchedEntries.length < 2) {
         confidence -= 0.15;
     }
-    // 维度 2: 分类一致性（权重 0.35）— ambiguity 非 low 或 strategy 为 skip 时扣分
     if (classification.ambiguity === "high") {
         confidence -= 0.35;
     }
     else if (classification.ambiguity === "medium") {
         confidence -= 0.15;
     }
-    // 维度 3: 意图明确性（权重 0.30）— 关键词密度不足时扣分
     const keywords = extractKeywords(intent);
     if (keywords.length < 2) {
         confidence -= 0.20;
@@ -572,10 +1610,7 @@ export function checkCircuitBreaker(params) {
     else if (keywords.length < 3) {
         confidence -= 0.10;
     }
-    // 降级模式额外惩罚
-    if (degraded) {
-        confidence -= 0.10;
-    }
+    // degraded 已在上方 L1826 扣除 -0.35，此处不重复扣分
     confidence = Math.max(0, Math.min(1, confidence));
     if (confidence < CONFIDENCE_THRESHOLD) {
         return {
@@ -587,10 +1622,6 @@ export function checkCircuitBreaker(params) {
     }
     return { tripped: false, confidence };
 }
-/**
- * 生成头脑风暴结构: 逻辑盲区 + 三轨演进 + 闭环逼问。
- * 熔断触发时由 AI 补充具体内容，此处生成骨架。
- */
 function generateBrainstorm(intent, classification, _matchedEntries) {
     const taskLabel = classification.task_type === "feature" ? "新功能" :
         classification.task_type === "bugfix" ? "缺陷修复" :