soloforge 1.4.11 → 1.4.13

package/dist/adapters/claude_code/tools.js

@@ -125,21 +125,38 @@ function decodeIndexedJsonString(value) {
 function parseContractObject(value, fieldName) {
     if (value === undefined || value === null)
         return {};
-    const candidate = decodeIndexedJsonString(typeof value === "string"
-        ? (() => {
-            try {
-                return JSON.parse(value);
-            }
-            catch {
-                return undefined;
-            }
-        })()
-        : value);
+    // 字符串 → 尝试 JSON 解析（可能被 MCP 客户端序列化为 JSON 字符串）
+    let parsed;
+    if (typeof value === "string") {
+        try {
+            parsed = JSON.parse(value);
+        }
+        catch (parseErr) {
+            return { error: `${fieldName} 的 JSON 解析失败: ${parseErr.message}。请检查 JSON 格式是否正确` };
+        }
+    }
+    else {
+        parsed = value;
+    }
+    const candidate = decodeIndexedJsonString(parsed);
     if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
-        return { error: `${fieldName} 必须是对象或可解析为对象的 JSON 字符串` };
+        return { error: `${fieldName} 必须是 JSON 对象（当前类型: ${Array.isArray(candidate) ? "array" : typeof candidate}）。期望格式请参考 expected_schema` };
     }
     return { value: candidate };
 }
+/** 需要通过 parseContractObject 校验的契约字段列表 */
+const CONTRACT_OBJECT_FIELDS = [
+    "architecture_decision_workshop", "decision_workshop",
+    "technology_decision_contract", "technology_decision_record",
+    "detail_discipline_contract", "provided_details",
+    "first_principles_frame", "brainstorm_session",
+    "design_artifact_pack", "ood_solid_summary",
+    "backend_implementation_work_package", "code_observability_work_package",
+];
+/** 需要规范化的字段 */
+const NORMALIZED_FIELDS = {
+    decision_workshop: "decision_workshop",
+};
 // ── Zod Schema 定义 ──
 const ClassifySchema = {
     intent: z.string().describe("开发者意图描述"),
@@ -149,18 +166,18 @@ const ExpandSchema = {
     task_id: z.string().describe("sf_classify 返回的任务 ID"),
     clarification_answers: z.array(z.string()).optional().describe("对澄清问题的回答"),
     input_material_confirmations: z.array(z.string()).optional().describe("已确认安全的输入材料路径列表"),
-    architecture_decision_workshop: z.unknown().optional().describe("架构设计前已讨论并确认的六域决策记录"),
-    decision_workshop: z.unknown().optional().describe("通用决策研讨合同（技术选型/数据迁移/安全策略/部署/重构/第三方集成等）"),
-    technology_decision_contract: z.unknown().optional().describe("技术决策主权契约，含选项、推荐、证据、回滚计划和 human_gate_evidence"),
-    technology_decision_record: z.unknown().optional().describe("技术决策执行记录，记录已批准/已实现等显式决策状态"),
-    detail_discipline_contract: z.unknown().optional().describe("细节纪律契约，声明必须覆盖的边界、失败路径、回滚和证据维度"),
-    provided_details: z.unknown().optional().describe("细节纪律已提供证据，按 required_dimensions 映射为字符串数组"),
-    first_principles_frame: z.unknown().optional().describe("高影响任务的第一性原理框架"),
-    brainstorm_session: z.unknown().optional().describe("不确定项/方案选择的脑暴与方案探索会话"),
-    design_artifact_pack: z.unknown().optional().describe("设计产物包路径映射或已复验状态"),
-    ood_solid_summary: z.unknown().optional().describe("复杂编码任务的 OOD/SOLID 设计摘要"),
-    backend_implementation_work_package: z.unknown().optional().describe("后端接口实现的工程工作包"),
-    code_observability_work_package: z.unknown().optional().describe("代码可维护性与可观测性工作包"),
+    architecture_decision_workshop: z.record(z.unknown()).optional().describe("架构设计前六域决策记录。示例 {domains:[{domain:'backend',options:[{id:'opt-a',title:'...'}],recommended_option_id:'opt-a',user_confirmation_ref:'confirm:...'}],status:'confirmed'}"),
+    decision_workshop: z.record(z.unknown()).optional().describe("通用决策研讨合同。示例 {activated_packs:['delivery_validation'],domains:[{domain:'delivery_validation',options:[{id:'opt-a',title:'...'}],recommended_option_id:'opt-a',user_confirmation_ref:'confirm:...'}],status:'confirmed'}"),
+    technology_decision_contract: z.record(z.unknown()).optional().describe("技术决策主权契约。示例 {decision_id:'TECH-001',decision_scope:'architecture',options:[{option_id:'opt-a',title:'A',description:'...'}],recommended_option:'opt-a',rejected_options:[{option:'opt-b',reason:'...'}],evidence:[{claim:'...',supporting_facts:['...']}],falsification:['...'],failure_conditions:['...'],validation_plan:['...'],rollback_or_exit_plan:['...'],human_gate_required:true,human_gate_evidence:'confirm:...',executable_without_human:false}"),
+    technology_decision_record: z.record(z.unknown()).optional().describe("技术决策执行记录。示例 {decision_id:'TECH-001',selected_option:'opt-a',status:'approved',approved_by:'user',evidence_refs:['confirm:...']}"),
+    detail_discipline_contract: z.record(z.unknown()).optional().describe("细节纪律契约。示例 {contract_id:'detail-001',required_dimensions:['boundary','failure_path','rollback'],blocking_dimensions:['boundary'],status:'ready'}"),
+    provided_details: z.record(z.unknown()).optional().describe("细节纪律已提供证据。示例 {boundary:['只检查 readiness，不改代码'],failure_path:['unknown 时标记证据不足'],rollback:['无写入，无需回滚']}"),
+    first_principles_frame: z.record(z.unknown()).optional().describe("高影响任务第一性原理框架。示例 {fundamental_need:'...',known_facts:['...'],assumptions:['...'],candidate_solutions:[{solution_id:'s1',description:'...',complexity:'low'}],simplest_viable_solution:'s1',chosen_solution:'s1',falsification_questions:['...'],why_not_legacy_path:'...'}"),
+    brainstorm_session: z.record(z.unknown()).optional().describe("不确定项/方案选择会话。示例 {trigger:'uncertainty',options:[{option_id:'opt-a',title:'...',description:'...',pros:['...'],cons:['...']}],recommended_option_id:'opt-a',rejected_option_ids:['opt-b'],failure_conditions:['...'],brainstorm_status:'options_ready'}"),
+    design_artifact_pack: z.record(z.unknown()).optional().describe("设计产物包路径映射或复验状态。示例 {status:'implementation_ready',paths:{architecture_document:'docs/architecture/01-架构设计文档.md'},verification_refs:['verification:...']}"),
+    ood_solid_summary: z.record(z.unknown()).optional().describe("复杂编码任务 OOD/SOLID 摘要。示例 {status:'confirmed',responsibilities:['...'],interfaces:['...'],risks:['...'],evidence_refs:['...']}"),
+    backend_implementation_work_package: z.record(z.unknown()).optional().describe("后端接口实现工程工作包。示例 {status:'confirmed',api_boundary:['...'],transaction_boundary:['...'],error_contract:['...'],evidence_refs:['...']}"),
+    code_observability_work_package: z.record(z.unknown()).optional().describe("代码可维护性与可观测性工作包。示例 {status:'confirmed',logging_plan:['...'],comment_plan:['...'],sensitive_logging_policy:'redact',evidence_refs:['...']}"),
 };
 const VerifySchema = {
     task_id: z.string().describe("任务 ID"),
@@ -178,7 +195,7 @@ const LearnSchema = {
 };
 const StatusSchema = {
     task_id: z.string().optional().describe("任务 ID（不传则查当前任务）"),
-    action: z.enum(["current", "recent", "resume", "cancel", "archive_stale"]).optional().describe("操作类型"),
+    action: z.enum(["current", "recent", "resume", "cancel", "archive_stale", "retry_expand"]).optional().describe("操作类型"),
     confirm: z.boolean().optional().describe("确认执行会写入状态的操作，例如 cancel/archive_stale/job_cancel"),
     authorized: z.boolean().optional().describe("confirm 的兼容别名"),
     job_id: z.string().optional().describe("Job ID（用于 job_status / job_resume / job_cancel）"),
@@ -511,7 +528,7 @@ export async function checkLocalAcceptanceGate(params) {
 const HIGH_IMPACT_KEYWORDS = /架构|技术选型|数据库|框架|多端|跨模块|高影响|高风险|migration|技术路线|选型|rework/i;
 const UNCERTAINTY_KEYWORDS = /不确定|方案选择|多选项|权衡|脑暴|brainstorm|多方案|选型|比较/i;
 const DETAIL_INTENSIVE_KEYWORDS = /多步骤|复杂|跨模块|高风险|多端|分布式|微服务/i;
-const LOW_RISK_ROUTES = new Set(["skip_chat", "direct_answer", "operation", "planning", "review", "source_extraction"]);
+const LOW_RISK_ROUTES = new Set(["skip_chat", "direct_answer", "operation", "planning", "review", "source_extraction", "acceptance"]);
 /** 技术选型/架构/数据库/框架/高影响决策 → 需 decision sovereignty gate */
 export function requiresDecisionSovereignty(ctx, route) {
     if (!ctx)
@@ -607,7 +624,7 @@ export async function checkDecisionSovereigntyGate(params) {
     const decisionModule = await lazyTechnologyDecision();
     const validation = decisionModule.validateTechnologyDecision(decisionContract);
     if (!validation.valid) {
-        return { allowed: false, reason_zh: `技术选型决策校验失败: ${validation.violations.join("; ")}` };
+        return { allowed: false, reason_zh: `技术选型决策校验失败: ${validation.violations.join("; ")}`, expected_schema: validation.expected_schema };
     }
     // 有决策记录时评估执行状态
     const decisionRecord = params.ctx.technology_decision_record;
@@ -672,7 +689,7 @@ export async function checkFirstPrinciplesGate(params) {
     const fpModule = await lazyFirstPrinciples();
     const validation = fpModule.validateFirstPrinciplesForHighImpact(fpFrame);
     if (!validation.passed) {
-        return { allowed: false, reason_zh: `高影响任务缺第一性原理推理: ${validation.violations.join("; ")}`, failures: validation.violations };
+        return { allowed: false, reason_zh: `高影响任务缺第一性原理推理: ${validation.violations.join("; ")}`, failures: validation.violations, expected_schema: validation.expected_schema };
     }
     return { allowed: true };
 }
@@ -695,7 +712,7 @@ export async function checkBrainstormGate(params) {
     const brainstormModule = await lazyBrainstormContract();
     const validation = brainstormModule.validateBrainstormSession(brainstormSession);
     if (!validation.valid) {
-        return { allowed: false, reason_zh: `方案探索不完整: ${validation.violations.join("; ")}`, violations: validation.violations };
+        return { allowed: false, reason_zh: `方案探索不完整: ${validation.violations.join("; ")}`, violations: validation.violations, expected_schema: validation.expected_schema };
     }
     // 脑暴推荐永远不能自动执行 — 需 Decision Sovereignty human gate
     const canAutoExec = brainstormModule.canBrainstormAutoExecute(brainstormSession);
@@ -1329,7 +1346,7 @@ export async function registerTools(server, deps) {
             }
             catch (err) {
                 const errorNextTools = name === "sf_expand"
-                    ? ["sf_status", "sf_debug", "sf_governance_report"]
+                    ? ["sf_expand", "sf_status", "sf_debug", "sf_governance_report"]
                     : contract.default_next_tools;
                 const errorForbiddenTools = name === "sf_expand"
                     ? ["sf_verify", "sf_review", "sf_deliver", "sf_scaffold"]
@@ -1484,161 +1501,27 @@ export async function registerTools(server, deps) {
         if (!ctx || !ctx.classification) {
             return { result: { error: "任务不存在或尚未分类，请先调用 sf_classify" } };
         }
-        const existingArchitectureWorkshop = parseContractObject(ctx.architecture_decision_workshop, "architecture_decision_workshop");
-        if (existingArchitectureWorkshop.error) {
-            return { result: { error: existingArchitectureWorkshop.error, status: "invalid_input" } };
-        }
-        const existingDecisionWorkshop = parseContractObject(ctx.decision_workshop, "decision_workshop");
-        if (existingDecisionWorkshop.error) {
-            return { result: { error: existingDecisionWorkshop.error, status: "invalid_input" } };
-        }
-        const existingTechnologyDecisionContract = parseContractObject(ctx.technology_decision_contract, "technology_decision_contract");
-        if (existingTechnologyDecisionContract.error) {
-            return { result: { error: existingTechnologyDecisionContract.error, status: "invalid_input" } };
-        }
-        const existingTechnologyDecisionRecord = parseContractObject(ctx.technology_decision_record, "technology_decision_record");
-        if (existingTechnologyDecisionRecord.error) {
-            return { result: { error: existingTechnologyDecisionRecord.error, status: "invalid_input" } };
-        }
-        const existingDetailContract = parseContractObject(ctx.detail_discipline_contract, "detail_discipline_contract");
-        if (existingDetailContract.error) {
-            return { result: { error: existingDetailContract.error, status: "invalid_input" } };
-        }
-        const existingProvidedDetails = parseContractObject(ctx.provided_details, "provided_details");
-        if (existingProvidedDetails.error) {
-            return { result: { error: existingProvidedDetails.error, status: "invalid_input" } };
-        }
-        const existingFirstPrinciplesFrame = parseContractObject(ctx.first_principles_frame, "first_principles_frame");
-        if (existingFirstPrinciplesFrame.error) {
-            return { result: { error: existingFirstPrinciplesFrame.error, status: "invalid_input" } };
-        }
-        const existingBrainstormSession = parseContractObject(ctx.brainstorm_session, "brainstorm_session");
-        if (existingBrainstormSession.error) {
-            return { result: { error: existingBrainstormSession.error, status: "invalid_input" } };
-        }
-        const existingDesignArtifactPack = parseContractObject(ctx.design_artifact_pack, "design_artifact_pack");
-        if (existingDesignArtifactPack.error) {
-            return { result: { error: existingDesignArtifactPack.error, status: "invalid_input" } };
-        }
-        const existingOodSolidSummary = parseContractObject(ctx.ood_solid_summary, "ood_solid_summary");
-        if (existingOodSolidSummary.error) {
-            return { result: { error: existingOodSolidSummary.error, status: "invalid_input" } };
-        }
-        const existingBackendImplementationWorkPackage = parseContractObject(ctx.backend_implementation_work_package, "backend_implementation_work_package");
-        if (existingBackendImplementationWorkPackage.error) {
-            return { result: { error: existingBackendImplementationWorkPackage.error, status: "invalid_input" } };
-        }
-        const existingCodeObservabilityWorkPackage = parseContractObject(ctx.code_observability_work_package, "code_observability_work_package");
-        if (existingCodeObservabilityWorkPackage.error) {
-            return { result: { error: existingCodeObservabilityWorkPackage.error, status: "invalid_input" } };
-        }
-        if (existingArchitectureWorkshop.value)
-            ctx.architecture_decision_workshop = existingArchitectureWorkshop.value;
-        if (existingDecisionWorkshop.value) {
-            ctx.decision_workshop = (await lazyDecisionWorkshop()).normalizeDecisionWorkshopContract(existingDecisionWorkshop.value, args.task_id) ?? existingDecisionWorkshop.value;
-        }
-        if (existingTechnologyDecisionContract.value)
-            ctx.technology_decision_contract = existingTechnologyDecisionContract.value;
-        if (existingTechnologyDecisionRecord.value)
-            ctx.technology_decision_record = existingTechnologyDecisionRecord.value;
-        if (existingDetailContract.value)
-            ctx.detail_discipline_contract = existingDetailContract.value;
-        if (existingProvidedDetails.value)
-            ctx.provided_details = existingProvidedDetails.value;
-        if (existingFirstPrinciplesFrame.value)
-            ctx.first_principles_frame = existingFirstPrinciplesFrame.value;
-        if (existingBrainstormSession.value)
-            ctx.brainstorm_session = existingBrainstormSession.value;
-        if (existingDesignArtifactPack.value)
-            ctx.design_artifact_pack = existingDesignArtifactPack.value;
-        if (existingOodSolidSummary.value)
-            ctx.ood_solid_summary = existingOodSolidSummary.value;
-        if (existingBackendImplementationWorkPackage.value)
-            ctx.backend_implementation_work_package = existingBackendImplementationWorkPackage.value;
-        if (existingCodeObservabilityWorkPackage.value)
-            ctx.code_observability_work_package = existingCodeObservabilityWorkPackage.value;
-        if (args.architecture_decision_workshop) {
-            const parsed = parseContractObject(args.architecture_decision_workshop, "architecture_decision_workshop");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.architecture_decision_workshop = parsed.value;
-        }
-        if (args.decision_workshop) {
-            const parsed = parseContractObject(args.decision_workshop, "decision_workshop");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.decision_workshop = (await lazyDecisionWorkshop()).normalizeDecisionWorkshopContract(parsed.value, args.task_id) ?? parsed.value;
-        }
-        if (args.technology_decision_contract) {
-            const parsed = parseContractObject(args.technology_decision_contract, "technology_decision_contract");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.technology_decision_contract = parsed.value;
-        }
-        if (args.technology_decision_record) {
-            const parsed = parseContractObject(args.technology_decision_record, "technology_decision_record");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.technology_decision_record = parsed.value;
-        }
-        if (args.detail_discipline_contract) {
-            const parsed = parseContractObject(args.detail_discipline_contract, "detail_discipline_contract");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.detail_discipline_contract = parsed.value;
-        }
-        if (args.provided_details) {
-            const parsed = parseContractObject(args.provided_details, "provided_details");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.provided_details = parsed.value;
-        }
-        if (args.first_principles_frame) {
-            const parsed = parseContractObject(args.first_principles_frame, "first_principles_frame");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.first_principles_frame = parsed.value;
-        }
-        if (args.brainstorm_session) {
-            const parsed = parseContractObject(args.brainstorm_session, "brainstorm_session");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.brainstorm_session = parsed.value;
-        }
-        if (args.design_artifact_pack) {
-            const parsed = parseContractObject(args.design_artifact_pack, "design_artifact_pack");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.design_artifact_pack = parsed.value;
-        }
-        if (args.ood_solid_summary) {
-            const parsed = parseContractObject(args.ood_solid_summary, "ood_solid_summary");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.ood_solid_summary = parsed.value;
-        }
-        if (args.backend_implementation_work_package) {
-            const parsed = parseContractObject(args.backend_implementation_work_package, "backend_implementation_work_package");
-            if (parsed.error)
-                return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.backend_implementation_work_package = parsed.value;
-        }
-        if (args.code_observability_work_package) {
-            const parsed = parseContractObject(args.code_observability_work_package, "code_observability_work_package");
+        // 合并校验 + 应用：ctx 已存储值 → args 覆盖值，统一解析和规范化
+        let needsSave = false;
+        for (const field of CONTRACT_OBJECT_FIELDS) {
+            // args 优先，其次 ctx 已存储值
+            const raw = args[field] ?? ctx[field];
+            if (!raw)
+                continue;
+            const parsed = parseContractObject(raw, field);
             if (parsed.error)
                 return { result: { error: parsed.error, status: "invalid_input" } };
-            ctx.code_observability_work_package = parsed.value;
+            if (parsed.value) {
+                ctx[field] = field === "decision_workshop"
+                    ? ((await lazyDecisionWorkshop()).normalizeDecisionWorkshopContract(parsed.value, args.task_id) ?? parsed.value)
+                    : parsed.value;
+                needsSave = true;
+            }
         }
-        if (args.architecture_decision_workshop || args.decision_workshop
-            || args.technology_decision_contract || args.technology_decision_record
-            || args.detail_discipline_contract || args.provided_details
-            || args.first_principles_frame || args.brainstorm_session
-            || args.design_artifact_pack
-            || args.ood_solid_summary || args.backend_implementation_work_package || args.code_observability_work_package) {
+        if (needsSave)
             await taskContext.save(ctx);
-        }
-        // 状态守卫：classifying/expanding/clarifying → expanding
-        if (ctx.status === "classifying" || ctx.status === "clarifying") {
+        // 状态守卫：classifying/expanding/clarifying/failed → expanding
+        if (ctx.status === "classifying" || ctx.status === "clarifying" || ctx.status === "failed") {
             await taskContext.updateStatus(args.task_id, "expanding");
             ctx.status = "expanding";
         }
@@ -1699,6 +1582,7 @@ export async function registerTools(server, deps) {
                 plan_context: planContext,
                 input_material_confirmations: args.input_material_confirmations,
                 task_id: args.task_id,
+                brainstorm_session: ctx.brainstorm_session ?? undefined,
             });
         }
         catch (expandErr) {
@@ -1951,223 +1835,231 @@ export async function registerTools(server, deps) {
                 }
             }
         }
-        // ── S4 gates: 独立于 hasInstructionContract，由 requires* 触发判定 ──
-        // 问题十六: 技术选型决策主权 gate — 高影响技术决策缺证据时 blocked
-        {
-            const decisionGate = await checkDecisionSovereigntyGate({ ctx, route: expansionRoute });
-            if (!decisionGate.allowed) {
-                return {
-                    result: {
-                        error: decisionGate.reason_zh,
-                        status: "blocked",
-                        recovery: decisionGate.requires_human_gate ? "请提供技术决策确认证据（human_gate_evidence）" : "技术选型决策校验失败，请提供 technology_decision_contract",
-                    },
-                };
-            }
-        }
-        // 问题二十六: 细节纪律 gate — 复杂任务缺关键细节时 blocked
-        {
-            const detailGate = await checkDetailDisciplineGate({ ctx, route: expansionRoute });
-            if (!detailGate.allowed) {
-                return {
-                    result: {
-                        error: detailGate.reason_zh,
-                        missing_details: detailGate.missing_details,
-                        status: "blocked",
-                        recovery: "多步骤/复杂任务缺 detail_discipline_contract，请提供后重新 sf_expand",
-                    },
-                };
+        // ── S4 gates: 轻量路径（acceptance/review/read_only）整体跳过 ──
+        const isLightweightRoute = expansionRoute === "acceptance" || expansionRoute === "review"
+            || expansionRoute === "direct_answer" || expansionRoute === "analysis";
+        if (!isLightweightRoute) {
+            // ── S4 gates: 独立于 hasInstructionContract，由 requires* 触发判定 ──
+            // 问题十六: 技术选型决策主权 gate — 高影响技术决策缺证据时 blocked
+            {
+                const decisionGate = await checkDecisionSovereigntyGate({ ctx, route: expansionRoute });
+                if (!decisionGate.allowed) {
+                    return {
+                        result: {
+                            error: decisionGate.reason_zh,
+                            status: "blocked",
+                            expected_schema: decisionGate.expected_schema,
+                            recovery: decisionGate.requires_human_gate ? "请提供技术决策确认证据（human_gate_evidence）" : "技术选型决策校验失败，请按照 expected_schema 格式提供 technology_decision_contract",
+                        },
+                    };
+                }
             }
-        }
-        // 问题二十七: 第一性原理 gate — 高影响任务缺推理时 blocked
-        {
-            const fpGate = await checkFirstPrinciplesGate({ ctx, route: expansionRoute });
-            if (!fpGate.allowed) {
-                return {
-                    result: {
-                        error: fpGate.reason_zh,
-                        failures: fpGate.failures,
-                        status: "blocked",
-                        recovery: "高影响任务缺 first_principles_frame，请提供后重新 sf_expand",
-                    },
-                };
+            // 问题二十六: 细节纪律 gate — 复杂任务缺关键细节时 blocked
+            {
+                const detailGate = await checkDetailDisciplineGate({ ctx, route: expansionRoute });
+                if (!detailGate.allowed) {
+                    return {
+                        result: {
+                            error: detailGate.reason_zh,
+                            missing_details: detailGate.missing_details,
+                            status: "blocked",
+                            recovery: "多步骤/复杂任务缺 detail_discipline_contract，请提供后重新 sf_expand",
+                        },
+                    };
+                }
             }
-        }
-        // 问题四十二(brainstorm): 脑暴契约 gate — 不确定项缺方案探索时 blocked
-        {
-            const brainstormGate = await checkBrainstormGate({ ctx, route: expansionRoute });
-            if (!brainstormGate.allowed) {
-                return {
-                    result: {
-                        error: brainstormGate.reason_zh,
-                        violations: brainstormGate.violations,
-                        status: "blocked",
-                        recovery: "不确定项/方案选择缺 brainstorm_session，请提供后重新 sf_expand",
-                    },
-                };
+            // 问题二十七: 第一性原理 gate — 高影响任务缺推理时 blocked
+            {
+                const fpGate = await checkFirstPrinciplesGate({ ctx, route: expansionRoute });
+                if (!fpGate.allowed) {
+                    return {
+                        result: {
+                            error: fpGate.reason_zh,
+                            failures: fpGate.failures,
+                            expected_schema: fpGate.expected_schema,
+                            status: "blocked",
+                            recovery: "高影响任务缺 first_principles_frame，请按照 expected_schema 格式提供后重新 sf_expand",
+                        },
+                    };
+                }
             }
-        }
-        // 问题六十六/六十七/六十八: 编码前工程约束必须聚合返回。
-        // 不能让 OOD 或后端工程门禁抢先返回，遮蔽用户项目的注释/日志契约。
-        {
-            const preImplementationBlocks = [];
-            const preImplementationPayload = {};
-            const artifactDesignIntent = expansionRoute === "artifact_generation"
-                || ["architecture_design", "database_design", "api_design", "detailed_design"].includes(String(workflowIntent))
-                || /(?:架构|数据库|API|接口|OpenAPI).{0,12}(?:设计|规格|文档)|(?:设计|规格|文档).{0,12}(?:API|接口|OpenAPI)/i.test(ctx.intent);
-            const isImplementationRoute = !artifactDesignIntent && (expansionRoute === "code_change"
-                || String(workflowIntent) === "backend_api_implementation"
-                || String(workflowIntent) === "frontend_business_logic"
-                || /编码|实现|开发|controller|service|component/i.test(ctx.intent));
-            const traceabilityModule = await lazyTraceability();
-            const traceReport = isImplementationRoute
-                ? traceabilityModule.auditDesignImplementationTraceability(projectPath)
-                : {
-                    passed: true,
-                    matrix_exists: false,
-                    findings: [],
-                    checked_files: [],
-                    matrix_path: traceabilityModule.DEFAULT_DESIGN_IMPLEMENTATION_TRACEABILITY_PATH,
-                };
-            if (isImplementationRoute && !traceReport.passed) {
-                ctx.traceability_binding = {
-                    requirement_ids: [],
-                    prototype_ids: [],
-                    architecture_ids: [],
-                    detail_design_ids: [],
-                    phase_ids: [],
-                    slice_ids: [],
-                    acceptance_ids: [],
-                    status: "needs_backfill",
-                    findings: traceReport.findings.map((finding) => `${finding.code}: ${finding.message_zh}`),
-                };
-                await taskContext.save(ctx);
-                return {
-                    result: {
-                        error: "需求/原型/设计/切片/验收追踪链路未闭合，不得进入编码实现",
-                        status: "blocked",
-                        diagnostic_code: TOOL_DIAGNOSTIC_CODES.traceabilityMissing,
-                        traceability_findings: traceReport.findings,
-                        checked_files: traceReport.checked_files,
-                        matrix_path: traceReport.matrix_path,
-                        template_path: traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_TEMPLATE_PATH,
-                        recovery_command: traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_RECOVERY_COMMAND,
-                        recovery: `${traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_RECOVERY_GUIDANCE}。不得取消任务后直接写代码，不得改用 Bash 绕过追踪矩阵。`,
-                    },
-                };
+            // 问题四十二(brainstorm): 脑暴契约 gate — 不确定项缺方案探索时 blocked
+            {
+                const brainstormGate = await checkBrainstormGate({ ctx, route: expansionRoute });
+                if (!brainstormGate.allowed) {
+                    return {
+                        result: {
+                            error: brainstormGate.reason_zh,
+                            violations: brainstormGate.violations,
+                            expected_schema: brainstormGate.expected_schema,
+                            status: "blocked",
+                            recovery: "不确定项/方案选择缺 brainstorm_session，请按照 expected_schema 格式提供后重新 sf_expand",
+                        },
+                    };
+                }
             }
-            const traceBindingIds = traceabilityModule.extractTraceabilityBindingIds(ctx);
-            if (traceReport.matrix_exists && isImplementationRoute) {
-                const missingPrefixes = ["PHASE", "SLICE", "DD", "AC"].filter((prefix) => !traceBindingIds.some((id) => id.startsWith(`${prefix}-`)));
-                if (missingPrefixes.length > 0) {
+            // 问题六十六/六十七/六十八: 编码前工程约束必须聚合返回。
+            // 不能让 OOD 或后端工程门禁抢先返回，遮蔽用户项目的注释/日志契约。
+            {
+                const preImplementationBlocks = [];
+                const preImplementationPayload = {};
+                const artifactDesignIntent = expansionRoute === "artifact_generation"
+                    || ["architecture_design", "database_design", "api_design", "detailed_design"].includes(String(workflowIntent))
+                    || /(?:架构|数据库|API|接口|OpenAPI).{0,12}(?:设计|规格|文档)|(?:设计|规格|文档).{0,12}(?:API|接口|OpenAPI)/i.test(ctx.intent);
+                const isImplementationRoute = !artifactDesignIntent && (expansionRoute === "code_change"
+                    || String(workflowIntent) === "backend_api_implementation"
+                    || String(workflowIntent) === "frontend_business_logic"
+                    || /编码|实现|开发|controller|service|component/i.test(ctx.intent));
+                const traceabilityModule = await lazyTraceability();
+                const traceReport = isImplementationRoute
+                    ? traceabilityModule.auditDesignImplementationTraceability(projectPath)
+                    : {
+                        passed: true,
+                        matrix_exists: false,
+                        findings: [],
+                        checked_files: [],
+                        matrix_path: traceabilityModule.DEFAULT_DESIGN_IMPLEMENTATION_TRACEABILITY_PATH,
+                    };
+                if (isImplementationRoute && !traceReport.passed) {
                     ctx.traceability_binding = {
-                        requirement_ids: traceBindingIds.filter((id) => id.startsWith("REQ-")),
-                        prototype_ids: traceBindingIds.filter((id) => id.startsWith("PROTO-")),
-                        architecture_ids: traceBindingIds.filter((id) => id.startsWith("ARCH-")),
-                        detail_design_ids: traceBindingIds.filter((id) => id.startsWith("DD-")),
-                        phase_ids: traceBindingIds.filter((id) => id.startsWith("PHASE-")),
-                        slice_ids: traceBindingIds.filter((id) => id.startsWith("SLICE-")),
-                        acceptance_ids: traceBindingIds.filter((id) => id.startsWith("AC-")),
-                        status: "missing",
-                        findings: missingPrefixes.map((prefix) => `编码前缺少 ${prefix}-* 绑定`),
+                        requirement_ids: [],
+                        prototype_ids: [],
+                        architecture_ids: [],
+                        detail_design_ids: [],
+                        phase_ids: [],
+                        slice_ids: [],
+                        acceptance_ids: [],
+                        status: "needs_backfill",
+                        findings: traceReport.findings.map((finding) => `${finding.code}: ${finding.message_zh}`),
                     };
                     await taskContext.save(ctx);
                     return {
                         result: {
-                            error: "编码任务必须先绑定阶段、切片、详细设计和验收 ID",
-                            status: "awaiting_traceability_binding",
-                            diagnostic_code: TOOL_DIAGNOSTIC_CODES.traceabilityBindingMissing,
-                            missing_prefixes: missingPrefixes,
+                            error: "需求/原型/设计/切片/验收追踪链路未闭合，不得进入编码实现",
+                            status: "blocked",
+                            diagnostic_code: TOOL_DIAGNOSTIC_CODES.traceabilityMissing,
+                            traceability_findings: traceReport.findings,
+                            checked_files: traceReport.checked_files,
                             matrix_path: traceReport.matrix_path,
                             template_path: traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_TEMPLATE_PATH,
-                            recovery_command: "sf_expand",
-                            recovery: "在任务上下文或指令中明确本次实现对应的 PHASE-*、SLICE-*、DD-*、AC-*，再重新调用 sf_expand；不得脱离已确认设计直接编码，不得取消任务后改用 Bash/Edit/Write 直接实现",
+                            recovery_command: traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_RECOVERY_COMMAND,
+                            recovery: `${traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_RECOVERY_GUIDANCE}。不得取消任务后直接写代码，不得改用 Bash 绕过追踪矩阵。`,
                         },
                     };
                 }
-                ctx.traceability_binding = {
-                    requirement_ids: traceBindingIds.filter((id) => id.startsWith("REQ-")),
-                    prototype_ids: traceBindingIds.filter((id) => id.startsWith("PROTO-")),
-                    architecture_ids: traceBindingIds.filter((id) => id.startsWith("ARCH-")),
-                    detail_design_ids: traceBindingIds.filter((id) => id.startsWith("DD-")),
-                    phase_ids: traceBindingIds.filter((id) => id.startsWith("PHASE-")),
-                    slice_ids: traceBindingIds.filter((id) => id.startsWith("SLICE-")),
-                    acceptance_ids: traceBindingIds.filter((id) => id.startsWith("AC-")),
-                    status: "bound",
-                    findings: [],
-                };
-                preImplementationPayload.traceability_binding = ctx.traceability_binding;
-            }
-            const oodModule = await lazyOodSolid();
-            const oodGate = oodModule.evaluateOodDesignGate({
-                task_id: args.task_id,
-                intent: ctx.intent,
-                route: expansionRoute,
-                summary: ctx.ood_solid_summary,
-            });
-            if (oodGate.applicable) {
-                ctx.ood_solid_summary = oodGate.required_summary;
-                preImplementationPayload.ood_solid_summary = oodGate.required_summary;
-            }
-            if (!oodGate.allowed) {
-                preImplementationBlocks.push({
-                    code: TOOL_DIAGNOSTIC_CODES.oodMissingSummary,
-                    reason_zh: oodGate.reason_zh,
-                });
-            }
-            const backendModule = await lazyBackendImplementation();
-            const backendGate = backendModule.evaluateBackendImplementationGate({
-                task_id: args.task_id,
-                intent: ctx.intent,
-                route: expansionRoute,
-                work_package: ctx.backend_implementation_work_package,
-            });
-            if (backendGate.applicable) {
-                ctx.backend_implementation_work_package = backendGate.work_package;
-                preImplementationPayload.backend_implementation_work_package = backendGate.work_package;
-            }
-            if (!backendGate.allowed) {
-                preImplementationBlocks.push({
-                    code: TOOL_DIAGNOSTIC_CODES.backendMissingSummary,
-                    reason_zh: backendGate.reason_zh,
+                const traceBindingIds = traceabilityModule.extractTraceabilityBindingIds(ctx);
+                if (traceReport.matrix_exists && isImplementationRoute) {
+                    const missingPrefixes = ["PHASE", "SLICE", "DD", "AC"].filter((prefix) => !traceBindingIds.some((id) => id.startsWith(`${prefix}-`)));
+                    if (missingPrefixes.length > 0) {
+                        ctx.traceability_binding = {
+                            requirement_ids: traceBindingIds.filter((id) => id.startsWith("REQ-")),
+                            prototype_ids: traceBindingIds.filter((id) => id.startsWith("PROTO-")),
+                            architecture_ids: traceBindingIds.filter((id) => id.startsWith("ARCH-")),
+                            detail_design_ids: traceBindingIds.filter((id) => id.startsWith("DD-")),
+                            phase_ids: traceBindingIds.filter((id) => id.startsWith("PHASE-")),
+                            slice_ids: traceBindingIds.filter((id) => id.startsWith("SLICE-")),
+                            acceptance_ids: traceBindingIds.filter((id) => id.startsWith("AC-")),
+                            status: "missing",
+                            findings: missingPrefixes.map((prefix) => `编码前缺少 ${prefix}-* 绑定`),
+                        };
+                        await taskContext.save(ctx);
+                        return {
+                            result: {
+                                error: "编码任务必须先绑定阶段、切片、详细设计和验收 ID",
+                                status: "awaiting_traceability_binding",
+                                diagnostic_code: TOOL_DIAGNOSTIC_CODES.traceabilityBindingMissing,
+                                missing_prefixes: missingPrefixes,
+                                matrix_path: traceReport.matrix_path,
+                                template_path: traceabilityModule.DESIGN_IMPLEMENTATION_TRACEABILITY_TEMPLATE_PATH,
+                                recovery_command: "sf_expand",
+                                recovery: "在任务上下文或指令中明确本次实现对应的 PHASE-*、SLICE-*、DD-*、AC-*，再重新调用 sf_expand；不得脱离已确认设计直接编码，不得取消任务后改用 Bash/Edit/Write 直接实现",
+                            },
+                        };
+                    }
+                    ctx.traceability_binding = {
+                        requirement_ids: traceBindingIds.filter((id) => id.startsWith("REQ-")),
+                        prototype_ids: traceBindingIds.filter((id) => id.startsWith("PROTO-")),
+                        architecture_ids: traceBindingIds.filter((id) => id.startsWith("ARCH-")),
+                        detail_design_ids: traceBindingIds.filter((id) => id.startsWith("DD-")),
+                        phase_ids: traceBindingIds.filter((id) => id.startsWith("PHASE-")),
+                        slice_ids: traceBindingIds.filter((id) => id.startsWith("SLICE-")),
+                        acceptance_ids: traceBindingIds.filter((id) => id.startsWith("AC-")),
+                        status: "bound",
+                        findings: [],
+                    };
+                    preImplementationPayload.traceability_binding = ctx.traceability_binding;
+                }
+                const oodModule = await lazyOodSolid();
+                const oodGate = oodModule.evaluateOodDesignGate({
+                    task_id: args.task_id,
+                    intent: ctx.intent,
+                    route: expansionRoute,
+                    summary: ctx.ood_solid_summary,
                 });
-            }
-            if (ctx.classification.task_type !== "scaffold") {
-                const obsModule = await lazyCodeObservability();
-                const obsGate = obsModule.evaluateCodeObservabilityGate({
+                if (oodGate.applicable) {
+                    ctx.ood_solid_summary = oodGate.required_summary;
+                    preImplementationPayload.ood_solid_summary = oodGate.required_summary;
+                }
+                if (!oodGate.allowed) {
+                    preImplementationBlocks.push({
+                        code: TOOL_DIAGNOSTIC_CODES.oodMissingSummary,
+                        reason_zh: oodGate.reason_zh,
+                    });
+                }
+                const backendModule = await lazyBackendImplementation();
+                const backendGate = backendModule.evaluateBackendImplementationGate({
                     task_id: args.task_id,
                     intent: ctx.intent,
                     route: expansionRoute,
-                    changed_files: ctx.execution?.changed_files,
-                    work_package: ctx.code_observability_work_package,
+                    work_package: ctx.backend_implementation_work_package,
                 });
-                if (obsGate.applicable) {
-                    ctx.code_observability_work_package = obsGate.work_package;
-                    preImplementationPayload.code_observability_work_package = obsGate.work_package;
+                if (backendGate.applicable) {
+                    ctx.backend_implementation_work_package = backendGate.work_package;
+                    preImplementationPayload.backend_implementation_work_package = backendGate.work_package;
                 }
-                if (!obsGate.allowed) {
+                if (!backendGate.allowed) {
                     preImplementationBlocks.push({
-                        code: TOOL_DIAGNOSTIC_CODES.codeObservabilityWorkPackage,
-                        reason_zh: obsGate.reason_zh,
+                        code: TOOL_DIAGNOSTIC_CODES.backendMissingSummary,
+                        reason_zh: backendGate.reason_zh,
                     });
                 }
+                if (ctx.classification.task_type !== "scaffold") {
+                    const obsModule = await lazyCodeObservability();
+                    const obsGate = obsModule.evaluateCodeObservabilityGate({
+                        task_id: args.task_id,
+                        intent: ctx.intent,
+                        route: expansionRoute,
+                        changed_files: ctx.execution?.changed_files,
+                        work_package: ctx.code_observability_work_package,
+                    });
+                    if (obsGate.applicable) {
+                        ctx.code_observability_work_package = obsGate.work_package;
+                        preImplementationPayload.code_observability_work_package = obsGate.work_package;
+                    }
+                    if (!obsGate.allowed) {
+                        preImplementationBlocks.push({
+                            code: TOOL_DIAGNOSTIC_CODES.codeObservabilityWorkPackage,
+                            reason_zh: obsGate.reason_zh,
+                        });
+                    }
+                }
+                if (Object.keys(preImplementationPayload).length > 0) {
+                    await taskContext.save(ctx);
+                }
+                if (preImplementationBlocks.length > 0) {
+                    return {
+                        result: {
+                            error: "编码前工程契约未全部确认，不得开始实现",
+                            status: "awaiting_implementation_contracts",
+                            diagnostic_codes: preImplementationBlocks.map((b) => b.code),
+                            blocking_findings: preImplementationBlocks,
+                            ...preImplementationPayload,
+                            recovery: "请同时确认 OOD/SOLID、后端工程边界、代码注释与日志契约后重新调用 sf_expand",
+                        },
+                    };
+                }
             }
-            if (Object.keys(preImplementationPayload).length > 0) {
-                await taskContext.save(ctx);
-            }
-            if (preImplementationBlocks.length > 0) {
-                return {
-                    result: {
-                        error: "编码前工程契约未全部确认，不得开始实现",
-                        status: "awaiting_implementation_contracts",
-                        diagnostic_codes: preImplementationBlocks.map((b) => b.code),
-                        blocking_findings: preImplementationBlocks,
-                        ...preImplementationPayload,
-                        recovery: "请同时确认 OOD/SOLID、后端工程边界、代码注释与日志契约后重新调用 sf_expand",
-                    },
-                };
-            }
-        }
+        } // end if (!isLightweightRoute) — 轻量路径跳过 S4 gates + 编码前工程约束
         // Input Material Contract: 处理 hard-blocking 结果
         // Privacy Gate: 隐私/敏感信息策略阻断
         const isBlocked = expansion.prompt.startsWith("## 阻塞：输入材料禁止读取")
@@ -2321,7 +2213,6 @@ export async function registerTools(server, deps) {
         // 存储膨胀结果
         try {
             await taskContext.setExpansion(args.task_id, expansion);
-            // 存储产物记录
             if (expansion.output_artifact_record) {
                 await taskContext.setArtifact(args.task_id, expansion.output_artifact_record);
             }
@@ -2356,6 +2247,46 @@ export async function registerTools(server, deps) {
             }
             throw updateErr;
         }
+        // 设置 plan_proposal_gate — 必须在 setExpansion/setArtifact/updateStatus 之后
+        // 这些操作各自 load-save 会覆盖之前的写入，所以 plan_proposal_gate 必须最后设置
+        {
+            const { evaluatePlanProposalGate, inferPlanGateTaskType } = await import("../../engine/plan_proposal_gate.js");
+            const routeForGate = expansion.workflow_trace?.route ?? expansionRoute ?? "code_change";
+            const taskTypeForGate = inferPlanGateTaskType(ctx.intent);
+            const isLightweight = routeForGate === "acceptance" || routeForGate === "review"
+                || routeForGate === "direct_answer" || routeForGate === "analysis";
+            try {
+                if (isLightweight) {
+                    await taskContext.setPlanProposalGate(args.task_id, {
+                        passed: true,
+                        plan_gate_status: "passed",
+                        required_level: "brief_plan",
+                        reason_zh: "轻量路径自动通过",
+                        violations: [],
+                        evidence_refs: [],
+                        blocked_actions: [],
+                    });
+                }
+                else {
+                    const gateResult = evaluatePlanProposalGate({
+                        task_id: args.task_id,
+                        task_type: taskTypeForGate,
+                        user_intent: ctx.intent,
+                        plan_level: "execution_plan",
+                        plan_summary_zh: ctx.intent.slice(0, 200),
+                        proposed_steps: [expansionRoute ?? "execute"],
+                        verification_plan: (expansion.acceptance?.automated ?? []).map((a) => a.description ?? String(a)),
+                        risks: [],
+                        evidence_refs: expansion.matched_knowledge ?? [],
+                    });
+                    await taskContext.setPlanProposalGate(args.task_id, gateResult);
+                }
+            }
+            catch (gateErr) {
+                // gate 设置失败不阻断主流程，后续写工具会重新检查
+                console.error(`[sf_expand] plan_proposal_gate 设置失败: ${gateErr.message}`);
+            }
+        }
         const expandPayload = Object.keys(advisories).length > 0
             ? { ...expansion, advisories }
             : expansion;
@@ -3160,6 +3091,22 @@ export async function registerTools(server, deps) {
                     result: { task_id: args.task_id, cancelled },
                 };
             }
+            case "retry_expand": {
+                if (!args.task_id) {
+                    return {
+                        result: { error: "重试 expand 需要 task_id" },
+                    };
+                }
+                const retried = await taskContext.retryExpand(args.task_id);
+                if (!retried) {
+                    return {
+                        result: { error: "任务不存在、非 failed 状态或缺少 classification，无法重试 expand", task_id: args.task_id },
+                    };
+                }
+                return {
+                    result: { task_id: args.task_id, retried: true, hint: "任务已恢复到 expanding 状态，可重新调用 sf_expand" },
+                };
+            }
             case "archive_stale": {
                 const stale = await detectStaleCurrentTask(taskContext.getStateDir());
                 const taskId = args.task_id ?? stale.task_id;