soloforge 1.3.1 → 1.3.3

package/dist/adapters/claude_code/tools.js

@@ -80,6 +80,12 @@ const lazyFirstPrinciples = createLazy(() => import("../../engine/first_principl
 const lazyBrainstormContract = createLazy(() => import("../../engine/brainstorm_contract.js"));
 const lazyArchitectureWorkshop = createLazy(() => import("../../engine/architecture_decision_workshop.js"));
 const lazyDesignArtifactPack = createLazy(() => import("../../engine/design_artifact_pack.js"));
+const lazyStandardAssetContract = createLazy(() => import("../../engine/standard_asset_contract.js"));
+const lazyTemplateVisibility = createLazy(() => import("../../engine/template_asset_visibility.js"));
+const lazyDecisionWorkshop = createLazy(() => import("../../engine/decision_workshop.js"));
+const lazyNavigation = createLazy(() => import("../../engine/next_action_planner.js"));
+const lazyOodSolid = createLazy(() => import("../../engine/ood_solid_contract.js"));
+const lazyBackendImplementation = createLazy(() => import("../../engine/backend_implementation_contract.js"));
 // ── Zod Schema 定义 ──
 const ClassifySchema = {
     intent: z.string().describe("开发者意图描述"),
@@ -90,7 +96,10 @@ const ExpandSchema = {
     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("通用决策研讨合同（技术选型/数据迁移/安全策略/部署/重构/第三方集成等）"),
     design_artifact_pack: z.unknown().optional().describe("设计产物包路径映射或已复验状态"),
+    ood_solid_summary: z.unknown().optional().describe("复杂编码任务的 OOD/SOLID 设计摘要"),
+    backend_implementation_work_package: z.unknown().optional().describe("后端接口实现的工程工作包"),
 };
 const VerifySchema = {
     task_id: z.string().describe("任务 ID"),
@@ -139,6 +148,24 @@ const RecordVerificationExecutionSchema = {
         evidence_id: z.string().describe("执行证据 ID"),
     })).describe("真实执行记录列表"),
 };
+const AcceptSchema = {
+    task_id: z.string().describe("任务 ID"),
+    confirm: z.boolean().describe("用户显式确认验收结果，必须为 true"),
+    confirmed_by: z.string().describe("执行确认的用户或审批者标识"),
+    confirmation_ref: z.string().describe("可审计的用户确认引用"),
+    acceptance_notes: z.string().describe("验收备注或不适用理由"),
+    run_mode: z.enum(["manual_review", "not_applicable"]).describe("验收模式"),
+    final_access: z.object({
+        frontend_urls: z.array(z.string()),
+        backend_urls: z.array(z.string()),
+        docs_or_swagger_urls: z.array(z.string()),
+        start_commands: z.array(z.string()),
+        stop_commands: z.array(z.string()),
+        running_status: z.string(),
+        manual_review_steps_zh: z.array(z.string()),
+        known_limits_zh: z.array(z.string()),
+    }).optional().describe("manual_review 模式下的真实本地访问证据"),
+};
 const DeliverSchema = {
     task_id: z.string().describe("任务 ID"),
     changed_files: z.array(z.string()).optional().describe("变更文件列表（不传则使用任务记录中的文件）"),
@@ -222,7 +249,7 @@ export function checkWriteToolPlanGate(params) {
 }
 /**
  * 施工指令契约门 — 写操作前检查施工指令完整性。
- * 问题五十八: 通过引擎模块函数真实消费。
+ * 通过引擎模块函数真实消费。
  * 调用链 1: registerInstructionIssueCandidate（无契约时创建候选 draft）
  * 调用链 2: enforceInstructionBeforeImplementation → checkInstructionCompleteness → validateInstructionContract
  */
@@ -282,7 +309,7 @@ export function checkDesignArtifactWriteGate(params) {
 }
 /**
  * 架构设计门 — 架构设计类任务膨胀前执行 reviewArchitectureDesign。
- * 问题四十九: Architecture Design Contract enforcement。
+ * Architecture Design Contract enforcement。
  */
 export async function checkArchitectureDesignGate(params) {
     const route = params.route;
@@ -309,7 +336,7 @@ export async function checkArchitectureDesignGate(params) {
 }
 /**
  * 架构决策研讨门 — 正式架构设计前六域决策必须闭合。
- * 问题六十一: 与是否存在施工指令契约无关，架构设计路由必经此门。
+ * 与是否存在施工指令契约无关，架构设计路由必经此门。
  */
 export async function checkArchitectureDecisionWorkshopGate(params) {
     const workshopModule = await lazyArchitectureWorkshop();
@@ -333,7 +360,7 @@ export async function checkArchitectureDecisionWorkshopGate(params) {
 }
 /**
  * 现有系统分析门 — 现有项目编码前必须先做分析。
- * 问题五十: Existing System Analysis Contract enforcement。
+ * Existing System Analysis Contract enforcement。
  */
 export async function checkExistingSystemAnalysisGate(params) {
     const archModule = await lazyExistingSystemAnalysis();
@@ -350,7 +377,7 @@ export async function checkExistingSystemAnalysisGate(params) {
 }
 /**
  * 编码就绪门 — 编码前必须有测试计划 + 验收标准。
- * 问题五十一: Coding Readiness / Test-First enforcement。
+ * Coding Readiness / Test-First enforcement。
  */
 export async function checkCodingReadinessGate(params) {
     if (!params.ctx)
@@ -375,7 +402,7 @@ export async function checkCodingReadinessGate(params) {
 }
 /**
  * 本地验收门 — 前端/全栈交付前必须有本地访问证据。
- * 问题五十二: Local Docker / Browser Acceptance enforcement。
+ * Local Docker / Browser Acceptance enforcement。
  */
 export async function checkLocalAcceptanceGate(params) {
     const acceptanceModule = await lazyLocalAcceptance();
@@ -397,6 +424,21 @@ export async function checkLocalAcceptanceGate(params) {
             required_but_missing: ["local_acceptance_evidence", "final_access_url"],
         };
     }
+    if (evidence.run_mode === "not_applicable") {
+        return {
+            allowed: false,
+            reason_zh: "该项目需要本地验收，不得以 not_applicable 代替真实访问证据",
+            required_but_missing: ["manual_review", "final_access_url"],
+        };
+    }
+    const finalAccessResult = acceptanceModule.validateFinalAccess(evidence.final_access, requirement.run_mode);
+    if (!finalAccessResult.passed) {
+        return {
+            allowed: false,
+            reason_zh: `本地验收证据不完整: ${finalAccessResult.blocking_reasons.join("; ")}`,
+            required_but_missing: ["validated_final_access"],
+        };
+    }
     return { allowed: true };
 }
 // ── S4 触发判定函数 ──
@@ -485,7 +527,7 @@ export function requiresBrainstorm(ctx, route) {
 }
 /**
  * 技术选型决策门 — 高影响技术决策需用户确认。
- * 问题十六: Decision Sovereignty enforcement。
+ * Decision Sovereignty enforcement。
  * 不依赖 hasInstructionContract — 触发由 requiresDecisionSovereignty 判定。
  */
 export async function checkDecisionSovereigntyGate(params) {
@@ -525,7 +567,7 @@ export async function checkDecisionSovereigntyGate(params) {
 }
 /**
  * 细节纪律门 — 复杂任务缺关键细节维度时阻断。
- * 问题二十六: Detail Discipline enforcement。
+ * Detail Discipline enforcement。
  * 不依赖 hasInstructionContract — 触发由 requiresDetailDiscipline 判定。
  */
 export async function checkDetailDisciplineGate(params) {
@@ -550,7 +592,7 @@ export async function checkDetailDisciplineGate(params) {
 }
 /**
  * 第一性原理门 — 高影响任务需目标/约束/本质问题/权衡。
- * 问题二十七: First Principles enforcement。
+ * First Principles enforcement。
  * 不依赖 hasInstructionContract — 触发由 requiresFirstPrinciples 判定。
  */
 export async function checkFirstPrinciplesGate(params) {
@@ -573,7 +615,7 @@ export async function checkFirstPrinciplesGate(params) {
 }
 /**
  * 脑暴/方案探索门 — 不确定项需多方案+推荐理由+用户确认。
- * 问题四十一-brainstorm: Brainstorm Contract enforcement。
+ * Brainstorm Contract enforcement。
  * 不依赖 hasInstructionContract — 触发由 requiresBrainstorm 判定。
  */
 export async function checkBrainstormGate(params) {
@@ -784,12 +826,14 @@ export async function registerTools(server, deps) {
     }
     /** State precheck: validate task status before contract guard */
     const STATE_PRECHECKS = {
+        sf_accept: ["executing", "verifying", "retrying"],
         sf_verify: ["executing", "retrying"],
         sf_record_verification_execution: ["verifying", "executing"],
         sf_learn: ["verifying", "executing"],
         sf_expand: ["classifying", "expanding", "clarifying"],
     };
     const STATE_ERROR_LABELS = {
+        sf_accept: "不可验收",
         sf_verify: "不可验证",
         sf_record_verification_execution: "不可录入验证结果",
         sf_learn: "不可学习",
@@ -1090,13 +1134,19 @@ export async function registerTools(server, deps) {
                 // 从 { result } 模式中提取数据
                 const data = raw?.result !== undefined ? raw.result : raw;
                 const hasError = !!(data && typeof data === "object" && "error" in data);
-                // 构建 trace
+                const recoveryNextTools = hasError && Array.isArray(data.recovery_next_tools)
+                    ? data.recovery_next_tools
+                    : contract.default_next_tools;
+                const recoveryForbiddenTools = hasError && Array.isArray(data.recovery_forbidden_tools)
+                    ? data.recovery_forbidden_tools
+                    : contract.forbidden_next_tools;
+                // 构建 trace；失败处理器可显式开放修复重验路径
                 const trace = createToolTrace({
                     tool_name: name, invocation_id: invocationId, task_id: taskId,
                     workflow_id: ctx?.expansion?.workflow_trace?.workflow_id,
                     actual_side_effects: effectiveSideEffects,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
+                    next_allowed_tools: recoveryNextTools,
+                    forbidden_tools: recoveryForbiddenTools,
                     authorization, bypass,
                 });
                 // 将 trace 写入 TaskContext
@@ -1107,8 +1157,8 @@ export async function registerTools(server, deps) {
                 const response = {
                     ...data,
                     tool_trace: trace,
-                    next_allowed_tools: contract.default_next_tools,
-                    forbidden_tools: contract.forbidden_next_tools,
+                    next_allowed_tools: recoveryNextTools,
+                    forbidden_tools: recoveryForbiddenTools,
                 };
                 // 基于状态的回退: 在响应中暴露降级 workflow
                 if (authorization.reason === "task in valid state for tool") {
@@ -1205,9 +1255,33 @@ export async function registerTools(server, deps) {
     debug("工具注册", "批量注册核心/辅助/知识维护工具...");
     // ── sf_classify: 意图分类入口，创建任务上下文并返回分类结果 ──
     registerSafeTool("sf_classify", "分析开发者意图，返回任务类型、风险、复杂度和执行策略", ClassifySchema, async (args) => {
+        const asksForNavigation = /(?:下一步|继续(?:做|执行|开发)?|现在(?:可以|能)(?:开始)?(?:写代码|编码|开发|测试|交付)|接下来(?:做什么|该做什么)|该(?:做什么|怎么继续))/i.test(args.intent);
+        if (asksForNavigation) {
+            const navigation = await (await lazyNavigation()).planNextAction(projectPath);
+            return {
+                result: {
+                    status: "navigation_required",
+                    reason_zh: "检测到阶段推进意图，必须先依据 SoloForge 状态规划下一步",
+                    navigation,
+                },
+            };
+        }
         // 检查是否存在进行中的任务
         const existing = await taskContext.getCurrentTask();
         if (existing && !["done", "failed"].includes(existing.status)) {
+            const navigation = await (await lazyNavigation()).planNextAction(projectPath);
+            if (navigation.stale_task?.is_stale) {
+                return {
+                    result: {
+                        status: "stale_task_requires_resolution",
+                        error: "存在陈旧任务指针，必须先选择恢复、归档或开始新任务",
+                        existing_task_id: existing.task_id,
+                        existing_status: existing.status,
+                        navigation,
+                        hint: "先调用 sf_navigation 查看可执行处理步骤，不得绕过 SoloForge 状态直接分析或编码",
+                    },
+                };
+            }
             return {
                 result: {
                     error: "存在未完成的任务",
@@ -1244,10 +1318,20 @@ export async function registerTools(server, deps) {
         if (args.architecture_decision_workshop) {
             ctx.architecture_decision_workshop = args.architecture_decision_workshop;
         }
+        if (args.decision_workshop) {
+            ctx.decision_workshop = args.decision_workshop;
+        }
         if (args.design_artifact_pack) {
             ctx.design_artifact_pack = args.design_artifact_pack;
         }
-        if (args.architecture_decision_workshop || args.design_artifact_pack) {
+        if (args.ood_solid_summary) {
+            ctx.ood_solid_summary = args.ood_solid_summary;
+        }
+        if (args.backend_implementation_work_package) {
+            ctx.backend_implementation_work_package = args.backend_implementation_work_package;
+        }
+        if (args.architecture_decision_workshop || args.decision_workshop || args.design_artifact_pack
+            || args.ood_solid_summary || args.backend_implementation_work_package) {
             await taskContext.save(ctx);
         }
         // 状态守卫：classifying/expanding/clarifying → expanding
@@ -1330,6 +1414,39 @@ export async function registerTools(server, deps) {
             gateway.endTask();
         }
         expansion.task_id = args.task_id;
+        const projectRoot = fss.realpathSync(projectPath);
+        const referencedMaterialPaths = new Set((expansion.input_materials ?? [])
+            .map((material) => material.path_or_ref)
+            .filter((materialPath) => typeof materialPath === "string" && materialPath.length > 0)
+            .map((materialPath) => path.resolve(projectRoot, materialPath)));
+        const confirmedProjectSourcePaths = (args.input_material_confirmations ?? [])
+            .map((materialPath) => path.resolve(projectRoot, materialPath))
+            .filter((absolutePath) => absolutePath === projectRoot || absolutePath.startsWith(`${projectRoot}${path.sep}`))
+            .filter((absolutePath) => referencedMaterialPaths.has(absolutePath))
+            .filter((absolutePath) => {
+            try {
+                return fss.statSync(absolutePath).isFile()
+                    && fss.realpathSync(absolutePath).startsWith(`${projectRoot}${path.sep}`);
+            }
+            catch {
+                return false;
+            }
+        });
+        const registerConfirmedProjectSources = (registry) => {
+            for (const absolutePath of confirmedProjectSourcePaths) {
+                const sourceRef = path.relative(projectRoot, absolutePath);
+                registry.register({
+                    source_type: "project_file",
+                    evidence_role: "project_source_file",
+                    authority: "authoritative",
+                    freshness: "current",
+                    permission: "allowed",
+                    scope: "confirmed_input_material",
+                    description: `已确认项目输入材料: ${sourceRef}`,
+                    source_ref: sourceRef,
+                });
+            }
+        };
         const workflowIntent = ctx.route_decision?.workflow_intent ?? ctx.classification.route_decision?.workflow_intent;
         // 问题六十: 高风险项目事实声明先过证据门，避免后续架构研讨门遮蔽无证据问题。
         {
@@ -1383,6 +1500,7 @@ export async function registerTools(server, deps) {
                         source_ref: `decision:${tdc.decision_id ?? args.task_id}`,
                     });
                 }
+                registerConfirmedProjectSources(evg.registry);
                 const evClaims = [
                     {
                         id: "claim-expand-0",
@@ -1463,6 +1581,34 @@ export async function registerTools(server, deps) {
             ctx.design_artifact_pack.user_confirmation_ref = ctx.architecture_decision_workshop?.document_output_confirmation_ref;
             await taskContext.save(ctx);
         }
+        // 问题六十一（通用）: 可组合决策包门禁
+        const dwModule = await lazyDecisionWorkshop();
+        const packMatch = dwModule.matchDecisionPacks({
+            workflow_intent: workflowIntent,
+            intent: ctx.intent,
+            task_type: ctx.classification?.task_type,
+        });
+        // 过滤掉架构（架构由上面的专用子包处理）
+        const nonArchPacks = packMatch.packs.filter((p) => p !== "architecture");
+        if (nonArchPacks.length > 0) {
+            const dwContract = ctx.decision_workshop ?? dwModule.createDecisionWorkshop(args.task_id, nonArchPacks, detectedArchitectureContext, packMatch.reasons.join("；"));
+            const dwGate = dwModule.evaluateDecisionWorkshop(dwContract);
+            ctx.decision_workshop = dwModule.applyDecisionWorkshopGate(dwContract);
+            await taskContext.save(ctx);
+            if (!dwGate.allowed) {
+                return {
+                    result: {
+                        error: `${packMatch.reasons.join("；")}，必须先完成决策研讨与用户确认`,
+                        status: "awaiting_confirmation",
+                        decision_workshop: ctx.decision_workshop,
+                        blocking_findings: dwGate.blocking_findings,
+                        next_domain: dwGate.next_domain,
+                        activated_packs: nonArchPacks,
+                        recovery: "请从当前待讨论域开始，提供候选方案、推荐理由、风险和用户确认后重新调用 sf_expand",
+                    },
+                };
+            }
+        }
         // 问题四十九/五十: 已有架构合同或现有系统证据的进一步审查。
         const expansionRoute = expansion.workflow_trace
             ? expansion.workflow_trace?.route
@@ -1558,6 +1704,56 @@ export async function registerTools(server, deps) {
                 };
             }
         }
+        // 问题六十六: 复杂业务编码必须先具备对象职责、接口和依赖方向摘要。
+        {
+            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;
+                await taskContext.save(ctx);
+            }
+            if (!oodGate.allowed) {
+                return {
+                    result: {
+                        error: oodGate.reason_zh,
+                        status: "awaiting_ood_design",
+                        diagnostic_code: "SF-OOD-6601",
+                        ood_solid_summary: oodGate.required_summary,
+                        recovery: "请确认对象职责、接口边界、依赖方向、变化点和 SOLID 风险后重新调用 sf_expand",
+                    },
+                };
+            }
+        }
+        // 问题六十七: 后端接口编码必须先确认工程边界与验收证据。
+        {
+            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;
+                await taskContext.save(ctx);
+            }
+            if (!backendGate.allowed) {
+                return {
+                    result: {
+                        error: backendGate.reason_zh,
+                        status: "awaiting_backend_contract",
+                        diagnostic_code: "SF-BACKEND-6701",
+                        backend_implementation_work_package: backendGate.work_package,
+                        recovery: "请补齐 DTO/校验、事务一致性、安全审计、契约对齐与测试证据后重新调用 sf_expand",
+                    },
+                };
+            }
+        }
         // Input Material Contract: 处理 hard-blocking 结果
         // Privacy Gate: 隐私/敏感信息策略阻断
         const isBlocked = expansion.prompt.startsWith("## 阻塞：输入材料禁止读取")
@@ -1628,6 +1824,7 @@ export async function registerTools(server, deps) {
                     source_ref: `decision:${_tdc.decision_id ?? args.task_id}`,
                 });
             }
+            registerConfirmedProjectSources(_evg.registry);
             const _evClaims = [
                 {
                     id: "claim-expand-0",
@@ -1761,6 +1958,102 @@ export async function registerTools(server, deps) {
                 result: { error: "任务不存在" },
             };
         }
+        const implementationFiles = args.changed_files.filter((file) => /\.(?:ts|tsx|js|jsx|java|kt|cs|go|py)$/.test(file)
+            && !/(?:^|\/)tests?\//.test(file));
+        if (implementationFiles.length > 0) {
+            const implementationContents = {};
+            for (const changedFile of implementationFiles) {
+                const absoluteFile = path.resolve(projectPath, changedFile);
+                try {
+                    if (absoluteFile.startsWith(`${path.resolve(projectPath)}${path.sep}`) && fss.statSync(absoluteFile).isFile()) {
+                        implementationContents[changedFile] = fss.readFileSync(absoluteFile, "utf-8");
+                    }
+                }
+                catch {
+                    // 文件缺失会由验证命令或现有产物检查报告。
+                }
+            }
+            const oodModule = await lazyOodSolid();
+            const oodGate = oodModule.evaluateOodDesignGate({
+                task_id: args.task_id,
+                intent: ctx.intent,
+                route: ctx.expansion?.workflow_trace?.route,
+                changed_files: implementationFiles,
+                summary: ctx.ood_solid_summary,
+            });
+            if (!oodGate.allowed) {
+                return {
+                    result: {
+                        error: oodGate.reason_zh,
+                        status: "blocked",
+                        diagnostic_code: "SF-OOD-6601",
+                        ood_solid_summary: oodGate.required_summary,
+                        recovery: "完成 OOD/SOLID 摘要后重新执行 sf_expand 与 sf_verify",
+                    },
+                };
+            }
+            const backendModule = await lazyBackendImplementation();
+            const backendGate = backendModule.evaluateBackendImplementationGate({
+                task_id: args.task_id,
+                intent: ctx.intent,
+                route: ctx.expansion?.workflow_trace?.route,
+                changed_files: implementationFiles,
+                work_package: ctx.backend_implementation_work_package,
+            });
+            if (!backendGate.allowed) {
+                return {
+                    result: {
+                        error: backendGate.reason_zh,
+                        status: "blocked",
+                        diagnostic_code: "SF-BACKEND-6701",
+                        backend_implementation_work_package: backendGate.work_package,
+                        recovery: "完成后端工程工作包后重新执行 sf_expand 与 sf_verify",
+                    },
+                };
+            }
+            const solidFindings = oodGate.applicable ? oodModule.reviewSolidCode(implementationContents) : [];
+            const backendFindings = backendGate.applicable ? backendModule.reviewBackendImplementationFiles(implementationContents) : [];
+            if (backendGate.applicable) {
+                const openApiPath = path.join(projectPath, "docs", "api", "openapi.yaml");
+                const apiMarkdownPath = path.join(projectPath, "docs", "architecture", "03-API接口规格文档.md");
+                const migrationDirectory = path.join(projectPath, "db", "migrations");
+                const openapiText = fss.existsSync(openApiPath) ? fss.readFileSync(openApiPath, "utf-8") : undefined;
+                const apiDocumentText = fss.existsSync(apiMarkdownPath) ? fss.readFileSync(apiMarkdownPath, "utf-8") : undefined;
+                const migrationText = fss.existsSync(migrationDirectory)
+                    ? fss.readdirSync(migrationDirectory).filter((name) => /\.sql$/i.test(name))
+                        .map((name) => fss.readFileSync(path.join(migrationDirectory, name), "utf-8")).join("\n")
+                    : undefined;
+                backendFindings.push(...backendModule.verifyBackendArtifactAlignment({
+                    openapiText,
+                    apiDocumentText,
+                    migrationText,
+                    sourceFiles: implementationContents,
+                }));
+            }
+            ctx.ood_solid_findings = solidFindings;
+            ctx.backend_implementation_findings = backendFindings;
+            await taskContext.save(ctx);
+            if (oodModule.hasBlockingSolidFindings(solidFindings)) {
+                return {
+                    result: {
+                        error: "OOD/SOLID 代码复验发现阻断项，需修复后重验",
+                        status: "blocked",
+                        diagnostic_code: "SF-OOD-6602",
+                        ood_solid_findings: solidFindings,
+                    },
+                };
+            }
+            if (backendModule.hasBlockingBackendFindings(backendFindings)) {
+                return {
+                    result: {
+                        error: "后端实现工程复验发现阻断项，需修复后重验",
+                        status: "blocked",
+                        diagnostic_code: "SF-BACKEND-6702",
+                        backend_implementation_findings: backendFindings,
+                    },
+                };
+            }
+        }
         // 问题六十二: 设计产物验证必须读取用户项目真实文件，不接受占位合同自证通过。
         const verifyWorkflowIntent = ctx.route_decision?.workflow_intent ?? ctx.classification?.route_decision?.workflow_intent;
         const touchesDesignArtifacts = args.changed_files.some((file) => /docs\/architecture\/|docs\/api\/|openapi|db\/(?:migrations|schema)|架构设计|数据库设计|API接口规格/i.test(file));
@@ -1789,6 +2082,83 @@ export async function registerTools(server, deps) {
                 };
             }
         }
+        // 问题六十三: 模板契约验证 — 按文件逐一匹配契约并校验
+        const sacModule = await lazyStandardAssetContract();
+        const formalArtifactContract = sacModule.matchTemplateContract({
+            output_artifact_kind: ctx.artifact_output?.kind,
+            workflow_intent: verifyWorkflowIntent,
+            route_decision: ctx.route_decision?.workflow_intent,
+        });
+        if (formalArtifactContract || !sacModule.isLowRiskTask({
+            route_decision: verifyWorkflowIntent ?? ctx.classification?.route_decision?.workflow_intent,
+            workflow_intent: verifyWorkflowIntent,
+            changed_files: args.changed_files,
+        })) {
+            for (const changedFile of args.changed_files) {
+                const absFile = path.join(projectPath, changedFile);
+                if (!fss.existsSync(absFile) || !/\.md$/.test(changedFile))
+                    continue;
+                // 按实际文件路径匹配契约（不再使用 changed_files[0] 的契约校验全部文件）
+                const perFileContract = sacModule.matchTemplateContract({
+                    output_artifact_kind: ctx.artifact_output?.kind,
+                    workflow_intent: verifyWorkflowIntent,
+                    route_decision: ctx.route_decision?.workflow_intent,
+                    file_path: changedFile,
+                });
+                if (!perFileContract)
+                    continue;
+                const content = fss.readFileSync(absFile, "utf-8");
+                // 草稿阻断下游消费 — 不再静默跳过
+                if (sacModule.isDraftDocument(content)) {
+                    ctx.repair_reverify_directive = {
+                        contract_id: perFileContract.asset_id,
+                        file_path: changedFile,
+                        status: "draft_blocked",
+                        repair_suggestion: `文件 ${changedFile} 仍为草稿状态，草稿不可用于实现。请完善内容后重新验证。`,
+                        blocked: true,
+                    };
+                    await taskContext.save(ctx);
+                    return {
+                        result: {
+                            error: `草稿文件 ${changedFile} 不可用于实现，需完善后重新验证`,
+                            status: "blocked",
+                            diagnostic_code: "SF-CONTRACT-DRAFT",
+                            template_contract_id: perFileContract.asset_id,
+                            recovery: "完善草稿内容后重新执行 sf_verify",
+                        },
+                    };
+                }
+                const contractResult = sacModule.verifyOutputAgainstContract(perFileContract, content, projectPath);
+                if (!contractResult.passed) {
+                    const repairDirective = sacModule.createRepairReverifyDirective(perFileContract, contractResult);
+                    ctx.repair_reverify_directive = {
+                        contract_id: perFileContract.asset_id,
+                        file_path: changedFile,
+                        status: "repair_required",
+                        repair_suggestion: repairDirective.repair_suggestion,
+                        blocked: true,
+                    };
+                    await taskContext.save(ctx);
+                    return {
+                        result: {
+                            error: `文件 ${changedFile} 模板契约验证未通过，进入修复重验闭环`,
+                            status: "blocked",
+                            diagnostic_code: "SF-CONTRACT-0003",
+                            template_contract_id: perFileContract.asset_id,
+                            missing_fields: contractResult.missing_fields,
+                            messages: contractResult.messages,
+                            repair_suggestion: repairDirective.repair_suggestion,
+                            recovery: "修复文档缺口后重新执行 sf_verify；不得只报告不修复",
+                        },
+                    };
+                }
+            }
+            // 全部契约验证通过 — 清零修复重验指令
+            if (ctx.repair_reverify_directive) {
+                delete ctx.repair_reverify_directive;
+                await taskContext.save(ctx);
+            }
+        }
         // RouteDecision 合同验证 — 无条件，在状态预检之前
         const rdFromCtx = ctx.route_decision ?? ctx.classification?.route_decision ?? null;
         const wtFromCtx = ctx.workflow_trace ?? ctx.expansion?.workflow_trace ?? null;
@@ -2445,12 +2815,55 @@ export async function registerTools(server, deps) {
         }, tracker);
         result.task_id = args.task_id;
         await taskContext.setCodeReview(args.task_id, result);
+        const contractContents = { ...(args.file_contents ?? {}) };
+        for (const changedFile of args.changed_files) {
+            if (contractContents[changedFile] !== undefined)
+                continue;
+            const absoluteFile = path.resolve(projectPath, changedFile);
+            try {
+                if (absoluteFile.startsWith(`${path.resolve(projectPath)}${path.sep}`) && fss.statSync(absoluteFile).isFile()) {
+                    contractContents[changedFile] = fss.readFileSync(absoluteFile, "utf-8");
+                }
+            }
+            catch {
+                // 无法读取的文件留给现有 reviewer 报告，不制造假结论。
+            }
+        }
+        const oodModule = await lazyOodSolid();
+        const solidFindings = oodModule.requiresOodSolidContract(ctx.intent, ctx.expansion?.workflow_trace?.route, args.changed_files)
+            || ctx.ood_solid_summary
+            ? [
+                ...oodModule.reviewSolidCode(contractContents),
+                ...oodModule.evaluateOverdesignRisk(ctx.intent, ctx.ood_solid_summary),
+            ]
+            : [];
+        const backendModule = await lazyBackendImplementation();
+        const backendFindings = backendModule.requiresBackendImplementationContract(ctx.intent, ctx.expansion?.workflow_trace?.route, args.changed_files)
+            || ctx.backend_implementation_work_package
+            ? backendModule.reviewBackendImplementationFiles(contractContents)
+            : [];
+        if (solidFindings.length > 0 || backendFindings.length > 0) {
+            const updatedCtx = await taskContext.load(args.task_id);
+            if (updatedCtx) {
+                updatedCtx.ood_solid_findings = solidFindings;
+                updatedCtx.backend_implementation_findings = backendFindings;
+                await taskContext.save(updatedCtx);
+            }
+        }
         // 决策契约 advisory: 校验 review 输出
         const decisionContract = (await lazyDecision()).validateDecisionOutput(result);
         const reviewExtras = {};
         if (!decisionContract.passed) {
             reviewExtras.decision_contract_advisory = decisionContract.advisory;
         }
+        if (solidFindings.length > 0)
+            reviewExtras.ood_solid_findings = solidFindings;
+        if (backendFindings.length > 0)
+            reviewExtras.backend_implementation_findings = backendFindings;
+        if (oodModule.hasBlockingSolidFindings(solidFindings) || backendModule.hasBlockingBackendFindings(backendFindings)) {
+            reviewExtras.delivery_blocked = true;
+            reviewExtras.diagnostic_code = "SF-IMPLEMENTATION-CONTRACT-REVIEW-BLOCKED";
+        }
         return { result: Object.keys(reviewExtras).length > 0 ? { ...result, ...reviewExtras } : result };
     });
     // ── sf_scaffold: 生成标准化代码骨架 ──
@@ -2481,6 +2894,103 @@ export async function registerTools(server, deps) {
         };
     });
     // ── sf_deliver: 自动提交、推送、创建 PR ──
+    // ── sf_accept: 记录任务验收证据（本地验收 + 产物确认） ──
+    registerSafeTool("sf_accept", "记录任务验收证据，解除 sf_deliver 的本地验收门和产物确认门", AcceptSchema, async (args) => {
+        const ctx = await taskContext.load(args.task_id);
+        if (!ctx) {
+            return { result: { error: "任务不存在" } };
+        }
+        const runMode = args.run_mode;
+        const notes = String(args.acceptance_notes ?? "").trim();
+        const confirmedBy = String(args.confirmed_by ?? "").trim();
+        const confirmationRef = String(args.confirmation_ref ?? "").trim();
+        if (args.confirm !== true || !confirmedBy || !confirmationRef || !notes) {
+            return {
+                result: {
+                    error: "验收必须包含显式确认、确认者、可审计确认引用和验收说明",
+                    diagnostic_code: "SF-ACCEPT-CONFIRMATION-REQUIRED",
+                    recovery_next_tools: ["sf_accept", "sf_status"],
+                    recovery_forbidden_tools: ["sf_deliver", "sf_scaffold", "sf_classify", "sf_expand"],
+                },
+            };
+        }
+        const currentVerification = ctx.verification_result ?? ctx.batch2_verification_result;
+        if (currentVerification?.status !== "passed") {
+            return {
+                result: {
+                    error: "验收前必须已有真实执行并通过的 verification_result",
+                    diagnostic_code: "SF-ACCEPT-VERIFICATION-REQUIRED",
+                    recovery_next_tools: ["sf_verify", "sf_record_verification_execution", "sf_status"],
+                    recovery_forbidden_tools: ["sf_deliver", "sf_scaffold", "sf_classify", "sf_expand"],
+                },
+            };
+        }
+        const evidenceRef = `acceptance:user_confirmation:${confirmationRef}`;
+        if (runMode === "manual_review") {
+            const acceptanceModule = await lazyLocalAcceptance();
+            if (!args.final_access) {
+                return {
+                    result: {
+                        error: "manual_review 验收缺少 final_access 真实访问证据",
+                        diagnostic_code: "SF-ACCEPT-FINAL-ACCESS-REQUIRED",
+                        recovery_next_tools: ["sf_accept", "sf_status"],
+                        recovery_forbidden_tools: ["sf_deliver", "sf_scaffold", "sf_classify", "sf_expand"],
+                    },
+                };
+            }
+            const finalAccessResult = acceptanceModule.validateFinalAccess(args.final_access, "local_dev_server");
+            if (!finalAccessResult.passed) {
+                return {
+                    result: {
+                        error: `manual_review 验收证据不完整: ${finalAccessResult.blocking_reasons.join("; ")}`,
+                        diagnostic_code: "SF-ACCEPT-FINAL-ACCESS-INVALID",
+                        recovery_next_tools: ["sf_accept", "sf_status"],
+                        recovery_forbidden_tools: ["sf_deliver", "sf_scaffold", "sf_classify", "sf_expand"],
+                    },
+                };
+            }
+        }
+        // 设置本地验收证据
+        ctx.local_acceptance_evidence = {
+            status: runMode === "manual_review" ? "passed" : "not_applicable",
+            run_mode: runMode,
+            confirmed_by: confirmedBy,
+            confirmation_ref: confirmationRef,
+            final_access: args.final_access ?? {
+                frontend_urls: [],
+                backend_urls: [],
+                docs_or_swagger_urls: [],
+                start_commands: [],
+                stop_commands: [],
+                running_status: "not_started",
+                manual_review_steps_zh: [notes],
+                known_limits_zh: [],
+            },
+            evidence_refs: [evidenceRef],
+        };
+        await taskContext.save(ctx);
+        let updatedCtx = ctx;
+        // 产物确认必须经过统一生命周期校验，不直接改写 status。
+        if (ctx.artifact_output && ctx.artifact_output.status === "verified") {
+            updatedCtx = await taskContext.updateArtifactStatus(args.task_id, {
+                status: "accepted",
+                evidenceRef,
+                hasAcceptance: true,
+            }) ?? ctx;
+        }
+        return {
+            result: {
+                task_id: args.task_id,
+                acceptance_status: "passed",
+                run_mode: runMode,
+                evidence_ref: evidenceRef,
+                artifact_transition: updatedCtx.artifact_output
+                    ? `${updatedCtx.artifact_output.status}`
+                    : "no_artifact",
+            },
+        };
+    });
+    // ── sf_deliver: 自动提交、推送、创建 PR ──
     registerSafeTool("sf_deliver", "验收后自动提交代码、推送、创建 PR 和生成变更日志", DeliverSchema, async (args) => {
         const ctx = await taskContext.load(args.task_id);
         if (!ctx) {
@@ -2493,6 +3003,42 @@ export async function registerTools(server, deps) {
         const h4DeliverWarning = !deliverIntegrity.clean
             ? { warning: `H4 advisory: ${deliverIntegrity.message}`, dirty_files: deliverIntegrity.dirty_files }
             : undefined;
+        // 模板契约修复指令优先于通用产物状态提示，确保客户端获得可执行的修复重验路径。
+        if (ctx.repair_reverify_directive) {
+            return {
+                result: {
+                    error: "存在未清零的模板契约修复指令，需完成修复重验后才能交付",
+                    diagnostic_code: "SF-CONTRACT-0003",
+                    repair_directive: ctx.repair_reverify_directive,
+                    recovery: "修复文档缺口后重新执行 sf_verify，验证通过后 repair_reverify_directive 自动清零",
+                    recovery_next_tools: ["sf_learn", "sf_verify", "sf_status"],
+                    recovery_forbidden_tools: ["sf_deliver", "sf_scaffold", "sf_classify", "sf_expand"],
+                },
+            };
+        }
+        // 问题六十六/六十七: 审查或验证阶段产生的工程硬失败不得进入交付。
+        const oodModule = await lazyOodSolid();
+        if (oodModule.hasBlockingSolidFindings(ctx.ood_solid_findings ?? [])) {
+            return {
+                result: {
+                    error: "OOD/SOLID 契约仍存在硬失败，不得交付",
+                    diagnostic_code: "SF-OOD-6602",
+                    findings: ctx.ood_solid_findings,
+                    recovery: "按 finding 修复职责或依赖边界，并重新执行 sf_review 与 sf_verify",
+                },
+            };
+        }
+        const backendModule = await lazyBackendImplementation();
+        if (backendModule.hasBlockingBackendFindings(ctx.backend_implementation_findings ?? [])) {
+            return {
+                result: {
+                    error: "后端实现工程契约仍存在硬失败，不得交付",
+                    diagnostic_code: "SF-BACKEND-6702",
+                    findings: ctx.backend_implementation_findings,
+                    recovery: "按 finding 修复后端边界、安全或一致性问题，并重新执行 sf_review 与 sf_verify",
+                },
+            };
+        }
         // 产物状态门控: deliver 需要产物状态为 accepted 且有证据
         if (ctx.artifact_output) {
             const status = ctx.artifact_output.status;
@@ -2574,6 +3120,7 @@ export async function registerTools(server, deps) {
         const metricsData = await (await lazyObservability()).collectDeliveryMetricSamples(taskContext.getStateDir());
         // acceptanceConfig: 从项目配置推断 project_run_mode
         const projectHasFrontend = config.tech_stack.frontend.lang && config.tech_stack.frontend.lang !== "none";
+        const projectHasBackend = config.tech_stack.backend.lang && config.tech_stack.backend.lang !== "none";
         const readinessReport = drModule.evaluateDeliveryReadiness(args.task_id, currentVResult, guardFindings, true, // scope_check — 已在 sf_verify 写入护栏中检查
         deliverLease.conflicts.length === 0, // lease_check — 无冲突即通过
         true, // privacy_check — 已在任务创建时脱敏
@@ -2603,7 +3150,7 @@ export async function registerTools(server, deps) {
             const localAcceptanceGate = await checkLocalAcceptanceGate({
                 ctx,
                 hasFrontend: !!projectHasFrontend,
-                hasBackend: !!config.tech_stack,
+                hasBackend: !!projectHasBackend,
                 hasDockerCompose: false,
                 hasDockerfile: false,
             });
@@ -2688,7 +3235,7 @@ export async function registerTools(server, deps) {
             task_id: args.task_id,
             verification_passed: currentVResult?.status === "passed",
             build_passed: (currentVResult?.passed_commands ?? 0) > 0,
-            browser_acceptance_passed: ctx.artifact_output?.status === "verified" || ctx.artifact_output === undefined,
+            browser_acceptance_passed: ctx.artifact_output?.status === "accepted" || ctx.artifact_output === undefined,
             guard_passed: guardFindings.length === 0 || guardFindings.every((f) => f.severity !== "hard_fail"),
             evidence_sufficient: (currentVResult?.evidence_ids?.length ?? 0) > 0,
             current_status: ctx.status === "done" ? "completed" : ctx.status,
@@ -3164,5 +3711,43 @@ export async function registerTools(server, deps) {
             result: { text: lines.join("\n") },
         };
     });
+    // ── sf_navigation: 工作流导航 — 问题六十五 ──
+    const NavigationSchema = {
+        type: "object",
+        properties: {
+            project_path: { type: "string", description: "项目路径（可选，默认当前目录）" },
+        },
+        required: [],
+    };
+    registerSafeTool("sf_navigation", "查询工作流导航: 当前项目阶段、任务阶段、下一步操作和禁止操作。用于\"下一步\"\"继续\"\"现在能写代码吗\"等模糊推进意图。不得靠模型经验回答，必须调用此工具获取真实导航状态", NavigationSchema, async (args) => {
+        const projectPath = args.project_path || config._projectPath || process.cwd();
+        const { planNextAction } = await import("../../engine/next_action_planner.js");
+        const plan = await planNextAction(projectPath);
+        return {
+            result: {
+                project_stage: plan.project_stage,
+                task_stage: plan.task_stage,
+                current_task_id: plan.current_task_id,
+                confidence: plan.confidence,
+                stage_evidence: plan.stage_evidence,
+                blocking_reasons: plan.blocking_reasons,
+                stale_task: plan.stale_task,
+                work_package: plan.work_package ? {
+                    id: plan.work_package.id,
+                    goal_zh: plan.work_package.goal_zh,
+                    description_zh: plan.work_package.description_zh,
+                    action: plan.work_package.action,
+                    tool_name: plan.work_package.tool_name,
+                    must_read: plan.work_package.must_read,
+                    forbidden_changes: plan.work_package.forbidden_changes,
+                    expected_outputs: plan.work_package.expected_outputs,
+                    acceptance_commands: plan.work_package.acceptance_commands,
+                } : null,
+                disallowed_actions: plan.disallowed_actions,
+                recommended_commands: plan.recommended_commands,
+                recommended_prompt_zh: plan.recommended_prompt_zh,
+            },
+        };
+    });
 }
 //# sourceMappingURL=tools.js.map