soloforge 1.3.4 → 1.3.6

package/dist/engine/release_readiness_gate.js

@@ -24,6 +24,7 @@
  * 18. 代码可维护性与可观测性契约行为验证
  * 19. 历史问题长期机制化行为验证
  * 20. 诊断码集中治理检查
+ * 21. 模板卫生与项目知识消费验证
  */
 import fs from "node:fs";
 import os from "node:os";
@@ -622,7 +623,12 @@ function checkTestPollution(rootDir, hardFail, _info) {
                 const checksImplementedVerified = content.includes("implemented_verified");
                 const checksFileExists = /existsSync/.test(content) && /required.*file/i.test(content);
                 const checksScenarioSelfAttest = /fixture_status.*ready|scenario.*status.*PASS/.test(content);
-                if (isScenarioMatrix) {
+                const hasPlaceholderTest = /场景注册占位/.test(content) || /expect\s*\(\s*true\s*\)\s*\.\s*toBe\s*\(\s*true\s*\)/.test(content) || /registered\s+only/.test(content);
+                const hasTodoPlaceholder = /\bit\s*\.\s*todo\s*\(/.test(content) || /\bdescribe\s*\.\s*todo\s*\(/.test(content);
+                if (hasPlaceholderTest || hasTodoPlaceholder) {
+                    categories.suspicious_test_pollution.push(rel);
+                }
+                else if (isScenarioMatrix) {
                     categories.batch_construction_test.push(rel);
                 }
                 else if (usefulContractExemptions.has(rel)) {
@@ -1127,19 +1133,22 @@ async function checkBatchIssueFormatConsistency(rootDir, hardFail, _info) {
     // 复用 scripts/batch_issue_details.mjs 的共享解析逻辑，不维护独立的问题识别规则
     const scriptPath = path.join(rootDir, "scripts", "batch_issue_details.mjs");
     let loadBatchIssueDetails;
+    let validateCanonicalIssueLedger;
     try {
         const mod = await import(scriptPath);
         loadBatchIssueDetails = mod.loadBatchIssueDetails;
+        validateCanonicalIssueLedger = mod.validateCanonicalIssueLedger;
     }
     catch (e) {
         hardFail("BATCH_ISSUE_FORMAT_INCONSISTENT", `无法加载共享解析脚本: ${e.message}`, ["scripts/batch_issue_details.mjs"], "构建系统", "共享解析脚本不可用", "修复脚本");
         return;
     }
-    if (!loadBatchIssueDetails) {
-        hardFail("BATCH_ISSUE_FORMAT_INCONSISTENT", "loadBatchIssueDetails 导出未找到", ["scripts/batch_issue_details.mjs"], "构建系统", "共享解析脚本导出不正确", "修复脚本");
+    if (!loadBatchIssueDetails || !validateCanonicalIssueLedger) {
+        hardFail("BATCH_ISSUE_FORMAT_INCONSISTENT", "共享解析脚本缺少 Batch 加载或 canonical ledger 校验导出", ["scripts/batch_issue_details.mjs"], "构建系统", "共享解析脚本导出不正确", "修复脚本");
         return;
     }
-    const expectedCounts = { 1: 19, 2: 12, 3: 9, 4: 13, 5: 6, 6: 5, 7: 2, 8: 1 };
+    const expectedCounts = { 1: 19, 2: 12, 3: 9, 4: 14, 5: 6, 6: 5, 7: 2, 8: 4 };
+    const parsedBatches = [];
     const requiredPerProblemSections = [
         "问题背景", "用户反馈 / 触发场景", "根因分析", "解决方案", "方案细节",
         "硬规则", "非目标", "影响范围", "落地文件", "验收标准", "回归风险",
@@ -1147,6 +1156,7 @@ async function checkBatchIssueFormatConsistency(rootDir, hardFail, _info) {
     ];
     for (let batch = 1; batch <= 8; batch++) {
         const details = loadBatchIssueDetails(batch, rootDir);
+        parsedBatches.push(details);
         if (!details.loaded) {
             hardFail("BATCH_ISSUE_FORMAT_INCONSISTENT", `Batch${batch} 问题集未加载: ${details.error}`, [`docs/SoloForge-Batch${batch}问题集.md`], `Batch${batch}`, "旧 gate 只检查文档存在，不验证是否可解析", "第 3 步统一格式");
             continue;
@@ -1190,7 +1200,27 @@ async function checkBatchIssueFormatConsistency(rootDir, hardFail, _info) {
         }
         _info(`  Batch${batch}: 已检查 (${details.issue_count} 个问题)`);
     }
-    _info("  说明: 本检查不修改文档。格式不一致问题将在第 3 步统一处理。");
+    try {
+        const roadmapPath = path.join(rootDir, "dist", "engine", "implementation_roadmap_registry.js");
+        const roadmap = await import(roadmapPath);
+        const roadmapProblems = roadmap.listAllProblems();
+        const ledgerFindings = validateCanonicalIssueLedger(parsedBatches, roadmapProblems, 71);
+        for (const finding of ledgerFindings) {
+            hardFail("CANONICAL_ISSUE_LEDGER_INCONSISTENT", finding.message, ["scripts/batch_issue_details.mjs", "src/engine/implementation_roadmap_registry.ts"], finding.issue_label ?? finding.problem_id ?? "canonical-ledger", "旧 gate 只校验单份文档格式与数量，不校验 Batch 文档和 roadmap 的唯一身份映射", "修正 canonical issue ID、文档归属或 roadmap 登记");
+        }
+        const roadmapFindings = roadmap.validateImplementationRoadmap()
+            .filter((finding) => finding.severity === "hard_fail");
+        for (const finding of roadmapFindings) {
+            hardFail("CANONICAL_ISSUE_LEDGER_INCONSISTENT", finding.message, ["src/engine/implementation_roadmap_registry.ts"], finding.subject_id ?? "roadmap", "旧 gate 不执行 roadmap 内部双向引用校验", "修正 ProblemEntry 与 ImplementationBatch 的双向归属");
+        }
+        if (ledgerFindings.length === 0 && roadmapFindings.length === 0) {
+            _info("  canonical ledger: 问题文档与 roadmap 的 71 个问题身份、归属一致");
+        }
+    }
+    catch (e) {
+        hardFail("CANONICAL_ISSUE_LEDGER_INCONSISTENT", `无法执行 canonical 问题账本对账: ${e.message}`, ["scripts/batch_issue_details.mjs", "src/engine/implementation_roadmap_registry.ts"], "canonical-ledger", "旧 gate 不加载 roadmap 执行文档双向对账", "先完成 build 并修复账本校验入口");
+    }
+    _info("  说明: 本检查不修改文档；格式或 canonical 身份不一致会阻断发布。");
 }
 // ── 机制身份一致性 ──
 async function checkMechanismIdentityConsistency(rootDir, hardFail, _info) {
@@ -1633,6 +1663,14 @@ async function checkImplementationContractBehavior(rootDir, hardFail, _info) {
         if (!backend.hasBlockingBackendFindings(alignmentFindings)) {
             hardFail("BACKEND_API_OPENAPI_DRIFT_FALSE_PASS", "problem-67: Markdown API 与 OpenAPI endpoint 漂移未阻断", ["src/engine/backend_implementation_contract.ts"], "problem-67", "契约对齐必须由行为检查证明", "修复 API/OpenAPI 漂移检测");
         }
+        const lombokFindings = backend.reviewBackendImplementationFiles({
+            "src/main/java/com/smartcare/staff/entity/Staff.java": "import jakarta.persistence.Entity; import lombok.Data; @Entity @Data public class Staff { private Long id; }",
+            "src/main/java/com/smartcare/staff/dto/StaffCreateRequest.java": "import lombok.Getter; import lombok.Setter; @Getter @Setter public class StaffCreateRequest { private String name; }",
+        });
+        const modelContractFindings = lombokFindings.filter((item) => item.category === "model_lombok_contract" && item.severity === "hard_fail");
+        if (modelContractFindings.length < 2) {
+            hardFail("BACKEND_MODEL_LOMBOK_CONTRACT_FALSE_PASS", "problem-71: Java Entity/DTO/VO/Request Lombok 分层契约未阻断错误注解", ["src/engine/backend_implementation_contract.ts", "templates/scaffolds/spring-boot/Entity.java.hbs", "templates/scaffolds/spring-boot/DTO.java.hbs"], "problem-71", "后端工程契约不能只治理 Controller/DTO 命名，还必须约束数据模型注解语义", "添加 Entity @Getter/@Setter、DTO/VO/Request @Data 的行为检查和脚手架默认值");
+        }
     }
     catch (e) {
         hardFail("IMPLEMENTATION_CONTRACT_EXECUTION_ERROR", `problem-66/67: 实现工程行为检查执行失败: ${e.message}`, ["src/engine/ood_solid_contract.ts", "src/engine/backend_implementation_contract.ts"], "problem-66/problem-67", "契约模块必须可运行并返回确定结果", "修复运行时异常");
@@ -1684,11 +1722,43 @@ async function checkReleaseIssueDesignPath(rootDir, hardFail, _info) {
         if (noTrace.length > 0) {
             hardFail("RELEASE_ISSUE_SCENARIO_NO_PRODUCTION_TRACE", `场景缺少 production_trace: ${noTrace.map(r => r.scenario_id).join("; ")}`, ["src/engine/release_issue_scenario_registry.ts"], "release-issues", "所有场景必须有 production_trace 记录真实入口", "为缺失场景添加 production_trace");
         }
+        // R10.1: 每个场景（非 engine_contract 声明）的 tool_entrypoint 必须包含真实工具名
+        const allRealToolNames = ["sf_classify", "sf_expand", "sf_verify", "sf_deliver", "sf_learn", "sf_accept", "sf_record_verification_execution", "sf_scaffold", "sf_navigation", "soloforge next", "checkArchitectureDecisionWorkshopGate", "planNextAction"];
+        const fakeTraceScenarios = execResults.filter(r => r.production_trace &&
+            !allRealToolNames.some(t => r.production_trace.tool_entrypoint.includes(t)) &&
+            !r.production_trace.gates_consumed?.includes("engine_contract"));
+        if (fakeTraceScenarios.length > 0) {
+            hardFail("RELEASE_ISSUE_SCENARIO_NO_PRODUCTION_TRACE", `场景 production_trace 不引用真实工具入口: ${fakeTraceScenarios.map(r => `${r.scenario_id}(entrypoint=${r.production_trace.tool_entrypoint})`).join("; ")}`, ["src/engine/release_issue_scenario_registry.ts"], "release-issues", "所有场景的 production_trace.tool_entrypoint 必须引用真实工具（sf_classify/sf_expand/adapter gate 等）", "用 createToolHarness 重写 runner");
+        }
         // R12: production_trace 的 diagnostic_codes 必须非空（来自工具返回值或函数调用结果）
         const noDiagCodes = execResults.filter(r => r.production_trace && (!r.production_trace.diagnostic_codes || r.production_trace.diagnostic_codes.length === 0));
         if (noDiagCodes.length > 0) {
             hardFail("RELEASE_ISSUE_SCENARIO_NO_PRODUCTION_TRACE", `场景 production_trace 缺少 diagnostic_codes: ${noDiagCodes.map(r => r.scenario_id).join("; ")}`, ["src/engine/release_issue_scenario_registry.ts"], "release-issues", "所有 production_trace 必须包含来自工具/函数返回值的 diagnostic_codes", "为场景添加真实 diagnostic_codes");
         }
+        // R14: architecture-workshop 非 low-risk 场景必须真正触发 workshop（不得假绿）
+        {
+            const archNonLowRisk = execResults.filter(r => r.scenario_id.startsWith("release-scenario-architecture-workshop-") &&
+                !r.scenario_id.includes("low-risk-skip"));
+            const fakeGreenPatterns = ["workshop=false", "domains=0", "no workshop", "blocked by earlier gate"];
+            const fakeGreens = archNonLowRisk.filter(r => r.status === "pass" && fakeGreenPatterns.some(p => r.evidence?.includes(p)));
+            if (fakeGreens.length > 0) {
+                hardFail("RELEASE_ISSUE_SCENARIO_NO_PRODUCTION_TRACE", `architecture-workshop 场景假绿: ${fakeGreens.map(r => `${r.scenario_id}(evidence=${r.evidence?.slice(0, 120)})`).join("; ")}`, ["src/engine/release_issue_scenario_registry.ts"], "release-issues", "非 low-risk 架构研讨场景必须真正触发 architecture_decision_workshop，不得把证据门阻断当作 pass", "确保场景提供足够证据通过 evidence grounding gate，使 workshop gate 能实际触发");
+            }
+            // 非 low-risk 场景必须同时有 sf_classify 和 sf_expand 入口
+            const missingEntrypoint = archNonLowRisk.filter(r => r.production_trace &&
+                (!r.production_trace.tool_entrypoint.includes("sf_classify") || !r.production_trace.tool_entrypoint.includes("sf_expand")));
+            if (missingEntrypoint.length > 0) {
+                hardFail("RELEASE_ISSUE_SCENARIO_NO_PRODUCTION_TRACE", `architecture-workshop 场景缺少 sf_classify 或 sf_expand 入口: ${missingEntrypoint.map(r => `${r.scenario_id}(entrypoint=${r.production_trace.tool_entrypoint})`).join("; ")}`, ["src/engine/release_issue_scenario_registry.ts"], "release-issues", "architecture-workshop 非 low-risk 场景必须同时通过 sf_classify 和 sf_expand 真实 MCP 工具执行", "使用 createToolHarness + callTool('sf_classify') + callTool('sf_expand') 重写 runner");
+            }
+        }
+        // R15: production_trace.diagnostic_codes 不得包含运行时异常
+        {
+            const runtimeErrorPattern = /Cannot read|TypeError|ReferenceError|^undefined$|uncaught exception|\.error\b/i;
+            const runtimeDiagCodes = execResults.filter(r => r.production_trace?.diagnostic_codes?.some(c => runtimeErrorPattern.test(c)));
+            if (runtimeDiagCodes.length > 0) {
+                hardFail("RELEASE_ISSUE_SCENARIO_DIAGNOSTIC_SWALLOWED_ERROR", `场景 production_trace.diagnostic_codes 包含运行时异常（不是业务/门禁诊断码）: ${runtimeDiagCodes.map(r => `${r.scenario_id}(codes=${r.production_trace.diagnostic_codes.filter(c => runtimeErrorPattern.test(c)).join("; ")})`).join("; ")}`, ["src/engine/release_issue_scenario_registry.ts"], "release-issues", "diagnostic_codes 必须来自真实业务/门禁诊断，不得把异常信息当作有效诊断码", "定位异常根因并修复，或确保场景提供完整输入使工具不抛异常");
+            }
+        }
         // R10: 每个 problem 必须至少有一个场景通过真实 MCP 工具入口执行
         const realToolNames = ["sf_classify", "sf_expand", "sf_verify", "sf_deliver", "sf_learn", "sf_accept", "sf_record_verification_execution", "sf_scaffold"];
         // 用 scenario_id 前缀识别 problem 归属
@@ -2301,6 +2371,80 @@ async function checkCodeObservabilityBehavior(rootDir, hardFail, _info) {
         if (!obs.hasBlockingObservabilityFindings(migrationFindings)) {
             hardFail("CODE_OBSERVABILITY_MIGRATION_FALSE_PASS", "problem-68: 迁移脚本无审计日志未被检测到", ["src/engine/code_maintainability_observability_contract.ts"], "problem-68", "数据修复脚本必须有审计日志", "修复 reviewMissingLogs 迁移脚本检测逻辑");
         }
+        // 行为验证: 普通 Spring 后端 Slice 的 CRUD/事务双写无日志无注释也必须被检测。
+        const smartCareSliceFindings = obs.verifyChangedFilesObservability({
+            changed_files: ["src/main/java/com/smartcare/staff/service/impl/StaffServiceImpl.java"],
+            file_contents: {
+                "src/main/java/com/smartcare/staff/service/impl/StaffServiceImpl.java": `@Service
+public class StaffServiceImpl implements StaffService {
+  @Transactional
+  public StaffVO create(StaffCreateRequest request) {
+    Staff staff = convert(request);
+    staffMapper.insert(staff);
+    SysUser user = buildUser(request);
+    sysUserMapper.insert(user);
+    return toVO(staff);
+  }
+  @Transactional
+  public void resign(Long staffId) {
+    staffMapper.updateStatus(staffId, StaffStatus.RESIGNED);
+    sysUserMapper.updateAccountStatus(staffId, 0);
+  }
+}`,
+            },
+            intent: "完成 Slice 2 机构设施与员工管理后端实现",
+        });
+        const smartCareBlocked = smartCareSliceFindings.some((f) => f.category === "missing_log_business_write" && f.severity === "hard_fail")
+            && smartCareSliceFindings.some((f) => f.category === "missing_comment_complex");
+        if (!smartCareBlocked) {
+            hardFail("CODE_OBSERVABILITY_BACKEND_SLICE_FALSE_PASS", "problem-68: 普通后端 Slice 的 Controller/Service 事务双写和级联规则无日志无注释未被阻断", ["src/engine/code_maintainability_observability_contract.ts"], "problem-68", "旧门禁只覆盖支付/安全/迁移，真实 CRUD 后端实现仍可无日志无注释通过", "扩展后端实现文件检测，覆盖 Controller/Service/DTO/Entity");
+        }
+        const javaDocAndChineseFindings = obs.verifyChangedFilesObservability({
+            changed_files: ["src/main/java/com/smartcare/staff/service/impl/StaffServiceImpl.java"],
+            file_contents: {
+                "src/main/java/com/smartcare/staff/service/impl/StaffServiceImpl.java": `@Service
+public class StaffServiceImpl implements StaffService {
+  public StaffVO create(StaffCreateRequest request) {
+    Staff staff = convert(request);
+    staffMapper.insert(staff);
+    logger.info("staff created staffId=" + staff.getId());
+    return toVO(staff);
+  }
+}`,
+            },
+            intent: "完成 Slice 2 员工管理后端实现",
+        });
+        const javaDocAndChineseBlocked = ["missing_class_doc", "missing_method_doc", "missing_important_line_comment", "non_chinese_log"].every((category) => javaDocAndChineseFindings.some((f) => f.category === category && f.severity === "hard_fail"));
+        if (!javaDocAndChineseBlocked) {
+            hardFail("CODE_OBSERVABILITY_CHINESE_DOC_CONTRACT_FALSE_PASS", "problem-68: 后端类/方法中文 Javadoc、关键行中文注释或中文日志缺失未被阻断", ["src/engine/code_maintainability_observability_contract.ts"], "problem-68", "只检查是否有日志/注释会放过英文日志、无类说明、无方法入参出参说明和关键行业务意图缺失", "扩展 reviewCommentQuality/reviewMissingLogs，强制中文日志、中文注释、类 Javadoc、方法 Javadoc 和关键行注释");
+        }
+        const crossStackFindings = obs.verifyChangedFilesObservability({
+            changed_files: ["src/routes/staff.route.ts", "app/api/staff.py", "src/pages/StaffForm.tsx"],
+            file_contents: {
+                "src/routes/staff.route.ts": `router.post('/staff', async (req, res) => {
+  const staff = await staffRepo.create(req.body);
+  await userRepo.create({ staffId: staff.id });
+  res.json(staff);
+});`,
+                "app/api/staff.py": `@router.post("/staff")
+async def create_staff(payload: StaffCreate):
+    staff = await staff_repo.create(payload)
+    await user_repo.create(staff_id=staff.id)
+    return staff`,
+                "src/pages/StaffForm.tsx": `export function StaffForm() {
+  async function handleSubmit(values) {
+    await apiClient.post('/api/institution/staff', values);
+    setStatus('created');
+  }
+  return <form onSubmit={handleSubmit}>...</form>;
+}`,
+            },
+            intent: "实现员工新增前后端接口与表单",
+        });
+        const crossStackBlocked = crossStackFindings.filter((f) => f.category === "missing_log_business_write" && f.severity === "hard_fail").length >= 3;
+        if (!crossStackBlocked) {
+            hardFail("CODE_OBSERVABILITY_CROSS_STACK_FALSE_PASS", "problem-68: 非 Spring 后端或前端业务写操作无日志/埋点未被阻断", ["src/engine/code_maintainability_observability_contract.ts"], "problem-68", "问题六十八不能只覆盖 Spring 后端文件", "扩展检测到 Nest/Express/FastAPI/Go/React/Vue 等通用实现形态");
+        }
     }
     catch (e) {
         hardFail("CODE_OBSERVABILITY_EXECUTION_ERROR", `problem-68: 可观测性行为检查执行失败: ${e.message}`, ["src/engine/code_maintainability_observability_contract.ts"], "problem-68", "契约模块必须可运行并返回确定结果", "修复运行时异常");
@@ -2393,7 +2537,238 @@ async function refund(order) { order.save(); logger.info("退款成功 orderId="
     }
     _info("  problem-68 代码可维护性与可观测性行为验证完成");
 }
+// ── 21. 模板卫生与用户项目知识消费验证 ──
+async function checkTemplateAndProjectKnowledgeHygiene(rootDir, hardFail, _info) {
+    try {
+        const matrix = await import(path.join(rootDir, "dist", "engine", "project_knowledge_system_regression_matrix.js"));
+        const report = matrix.validateProjectKnowledgeSystemMatrix?.();
+        if (!report?.passed) {
+            const messages = (report?.findings ?? []).map((finding) => `${finding.code}: ${finding.message}`).join("; ");
+            hardFail("PROJECT_KNOWLEDGE_SYSTEM_MATRIX_INCOMPLETE", `problem-69: 知识资产与项目规则消费体系 20 项防回归矩阵不完整: ${messages || "未知缺口"}`, ["src/engine/project_knowledge_system_regression_matrix.ts", "docs/SoloForge-Batch8问题集.md"], "problem-69", "旧门禁只检查部分项目知识行为，未覆盖用户讨论的 20 项完整细节", "补齐 20 项矩阵、生产入口、must-fail/must-pass 与文档引用");
+        }
+    }
+    catch (e) {
+        hardFail("PROJECT_KNOWLEDGE_SYSTEM_MATRIX_EXCEPTION", `problem-69: 知识资产与项目规则消费体系矩阵执行失败: ${e.message}`, ["src/engine/project_knowledge_system_regression_matrix.ts"], "problem-69", "项目知识体系矩阵必须可执行", "修复矩阵模块或编译产物");
+    }
+    const scaffoldDir = path.join(rootDir, "templates", "scaffolds");
+    const scaffoldFindings = [];
+    function scanScaffolds(dir) {
+        if (!fs.existsSync(dir))
+            return;
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                scanScaffolds(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const rel = path.relative(rootDir, full).replace(/\\/g, "/");
+            const lines = safeReadLines(full);
+            for (let i = 0; i < lines.length; i++) {
+                if (/\b(?:TODO|FIXME|HACK|XXX)\b/.test(lines[i])) {
+                    scaffoldFindings.push(`${rel}:${i + 1}`);
+                }
+            }
+        }
+    }
+    scanScaffolds(scaffoldDir);
+    for (const finding of scaffoldFindings) {
+        hardFail("TEMPLATE_SCAFFOLD_PLACEHOLDER_LEAK", `脚手架模板仍包含未落地占位标记: ${finding}`, [finding.split(":")[0]], "template-hygiene", "历史门禁只检查模板是否注册，不检查用户生成代码是否带 TODO/FIXME", "清理脚手架占位标记并补行为测试");
+    }
+    try {
+        const contractMod = await import(path.join(rootDir, "dist", "engine", "template_asset_contract_registry.js"));
+        const contracts = contractMod.listTemplateAssetContracts?.() ?? [];
+        const forbidden = /\b(?:Batch[1-8]|validate-batch|ReleaseFix|problem-\d+)\b/i;
+        for (const contract of contracts) {
+            if (!contract.user_visible)
+                continue;
+            if (!contract.path || !/\.(md|ya?ml|hbs|json)$/i.test(contract.path))
+                continue;
+            const abs = path.join(rootDir, contract.path);
+            const content = safeRead(abs);
+            if (!content || !forbidden.test(content))
+                continue;
+            hardFail("USER_VISIBLE_TEMPLATE_INTERNAL_TRACE", `用户可见模板泄漏内部施工语义: ${contract.path}`, [contract.path], "template-hygiene", "旧门禁只检查内置资产可见性，不检查用户可见模板内容是否混入内部批次/问题编号", "清理用户可见模板内部语义");
+        }
+    }
+    catch (e) {
+        hardFail("TEMPLATE_CONTRACT_AUDIT_FAILED", `无法执行用户可见模板内容审计: ${e.message}`, ["src/engine/template_asset_contract_registry.ts"], "template-hygiene", "模板内容卫生必须可运行审计", "修复模板合同注册表或编译产物");
+    }
+    try {
+        const obs = await import(path.join(rootDir, "dist", "engine", "code_maintainability_observability_contract.js"));
+        const ordinaryApiImplementationTriggers = obs.requiresCodeObservabilityContract?.("实现机构端入住列表接口", "code_change") === true;
+        if (!ordinaryApiImplementationTriggers) {
+            hardFail("CODE_OBSERVABILITY_BUSINESS_API_NOT_TRIGGERED", "problem-68: 普通业务接口实现未触发代码注释与日志契约，真实项目会绕过问题六十八", ["src/engine/code_maintainability_observability_contract.ts", "src/adapters/claude_code/tools.ts"], "problem-68", "旧行为只覆盖支付/安全等关键词，未覆盖普通 Controller/API/Service 编码", "扩展触发条件并在 sf_expand 聚合返回工作包");
+        }
+    }
+    catch (e) {
+        hardFail("CODE_OBSERVABILITY_TRIGGER_AUDIT_FAILED", `问题六十八触发审计执行失败: ${e.message}`, ["src/engine/code_maintainability_observability_contract.ts"], "problem-68", "触发判断必须可运行", "修复编译或导出");
+    }
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "soloforge-project-knowledge-"));
+    try {
+        const goodDir = path.join(tmp, ".soloforge", "knowledge", "rules");
+        fs.mkdirSync(goodDir, { recursive: true });
+        fs.writeFileSync(path.join(goodDir, "API响应规则.md"), `---
+id: smartcare-api-response-rule
+asset_kind: hard_rule
+routes:
+  - code_change
+  - artifact_generation
+primary_triggers:
+  - API
+  - 接口
+  - 响应
+tech_stack:
+  - spring
+enforcement:
+  level: hard_rule
+---
+# API 响应规则
+
+必须使用项目统一响应结构，错误码、字段表和 OpenAPI 保持一致。
+`, "utf-8");
+        const projectKnowledge = await import(path.join(rootDir, "dist", "engine", "project_knowledge_contract.js"));
+        const report = projectKnowledge.auditProjectKnowledge(tmp);
+        if (report.hard_fail_count !== 0 || report.injectable < 1) {
+            hardFail("PROJECT_KNOWLEDGE_RULE_NOT_CONSUMABLE", "用户项目 .soloforge/knowledge hard rule 未被识别为可消费规则", ["src/engine/project_knowledge_contract.ts"], "project-knowledge-consumption", "旧链路只同步/索引内置模板，未证明用户项目自定义规则可被承载消费", "修复项目知识合同审计与选择逻辑");
+        }
+        const selected = projectKnowledge.selectProjectKnowledgeForTask(report, {
+            intent: "实现机构端 API 接口统一响应",
+            route: "code_change",
+            tech_stack: ["spring"],
+        });
+        if (!selected.some((asset) => asset.id === "smartcare-api-response-rule")) {
+            hardFail("PROJECT_KNOWLEDGE_RULE_NOT_SELECTED", "用户项目自定义 hard rule 未按意图/路由/技术栈被选中", ["src/engine/project_knowledge_contract.ts"], "project-knowledge-consumption", "索引存在不等于任务会消费", "补齐 selectProjectKnowledgeForTask 行为和门禁");
+        }
+        const expander = await import(path.join(rootDir, "dist", "engine", "intent_expander.js"));
+        const expandResult = await expander.expand({
+            intent: "实现机构端 API 接口统一响应",
+            classification: {
+                task_type: "feature",
+                risk: "low",
+                complexity: "low",
+                ambiguity: "low",
+                affected_repos: ["backend"],
+                mode: "autonomous",
+                strategy: "full_pipeline",
+            },
+            projectPath: tmp,
+            config: {
+                name: "release-gate-project-knowledge",
+                tech_stack: {
+                    backend: { lang: "java", framework: "spring-boot", version: "3" },
+                    frontend: { lang: "typescript", framework: "react", version: "18" },
+                },
+                product_profile: "saas",
+                repos: [{ name: "backend", path: "backend", lang: "java", framework: "spring-boot", scope: ["backend/src/"] }],
+                build_commands: {
+                    backend: { build: "mvn compile", test: "mvn test", full: "mvn verify" },
+                    frontend: { build: "npm run build", test: "npm test", full: "npm test" },
+                },
+                scope: { backend: ["backend/src/"], frontend: ["src/"] },
+                _projectPath: tmp,
+            },
+            knowledgeIndex: { query: () => [], markUsed: () => { } },
+            route_decision: {
+                route: "code_change",
+                execution_shape: "code_execution",
+                mutation_allowed: true,
+                input_materials: [],
+                missing_required_inputs: [],
+                scope: { read_only: false },
+                constraints: [],
+                language_policy: { primary: "zh" },
+                confidence: 0.9,
+                evidence: [],
+                rejected_routes: [],
+                conflicts: [],
+                decision_version: 1,
+            },
+        });
+        if (!expandResult.project_knowledge?.selected?.some((asset) => asset.id === "smartcare-api-response-rule")
+            || !String(expandResult.prompt).includes("## 用户项目规则")) {
+            hardFail("PROJECT_KNOWLEDGE_NOT_IN_EXPAND_MAINPATH", "用户项目规则未进入 sf_expand 真实 prompt 和结构化结果", ["src/engine/intent_expander.ts", "src/engine/project_knowledge_contract.ts"], "project-knowledge-consumption", "审计/选择通过不等于 MCP 主链路会消费", "将项目规则接入 sf_expand 并补主链路测试");
+        }
+        const nextPlanner = await import(path.join(rootDir, "dist", "engine", "next_action_planner.js"));
+        const nextPlan = await nextPlanner.planNextAction(tmp);
+        if (!nextPlan.project_knowledge_context || nextPlan.project_knowledge_context.total < 1) {
+            hardFail("PROJECT_KNOWLEDGE_NOT_IN_NEXT", "soloforge next 未携带项目知识上下文，用户无法知道下一步会应用哪些项目规则", ["src/engine/next_action_planner.ts", "src/bin/soloforge.ts"], "project-knowledge-consumption", "旧导航只看阶段，不看项目规则", "将项目知识上下文接入 next JSON 和人类输出");
+        }
+        const badTmp = fs.mkdtempSync(path.join(os.tmpdir(), "soloforge-project-knowledge-bad-"));
+        try {
+            const badDir = path.join(badTmp, ".soloforge", "knowledge", "rules");
+            fs.mkdirSync(badDir, { recursive: true });
+            fs.writeFileSync(path.join(badDir, "未路由强规则.md"), "# 未路由强规则\n\n必须使用统一响应。", "utf-8");
+            const badReport = projectKnowledge.auditProjectKnowledge(badTmp);
+            if (badReport.hard_fail_count === 0) {
+                hardFail("PROJECT_KNOWLEDGE_UNROUTED_RULE_FALSE_PASS", "用户项目 hard rule 缺少 routes/primary_triggers 时错误放行", ["src/engine/project_knowledge_contract.ts"], "project-knowledge-consumption", "规则文件存在不等于可稳定消费", "对未路由 hard rule fail-closed");
+            }
+        }
+        finally {
+            fs.rmSync(badTmp, { recursive: true, force: true });
+        }
+        const conflictTmp = fs.mkdtempSync(path.join(os.tmpdir(), "soloforge-project-knowledge-conflict-"));
+        try {
+            const conflictDir = path.join(conflictTmp, ".soloforge", "knowledge", "rules");
+            fs.mkdirSync(conflictDir, { recursive: true });
+            fs.writeFileSync(path.join(conflictDir, "响应A.md"), `---
+id: response-a
+asset_kind: hard_rule
+routes: [code_change]
+primary_triggers: [API]
+conflict_group: api_response_format
+rule_value: ApiResponse
+enforcement:
+  level: hard_rule
+---
+# 响应 A
+
+必须使用 ApiResponse。
+`, "utf-8");
+            fs.writeFileSync(path.join(conflictDir, "响应B.md"), `---
+id: response-b
+asset_kind: hard_rule
+routes: [code_change]
+primary_triggers: [API]
+conflict_group: api_response_format
+rule_value: Result
+enforcement:
+  level: hard_rule
+---
+# 响应 B
+
+必须使用 Result。
+`, "utf-8");
+            const conflictReport = projectKnowledge.auditProjectKnowledge(conflictTmp);
+            if (!conflictReport.assets.some((asset) => asset.findings.some((finding) => finding.code === "PROJECT_KNOWLEDGE_RULE_CONFLICT"))) {
+                hardFail("PROJECT_KNOWLEDGE_CONFLICT_FALSE_PASS", "项目 API 响应等规则冲突未进入用户确认", ["src/engine/project_knowledge_contract.ts"], "project-knowledge-consumption", "旧项目知识审计只看是否可选中，不看项目规则之间互斥", "补冲突组/显式 conflicts_with 检测");
+            }
+        }
+        finally {
+            fs.rmSync(conflictTmp, { recursive: true, force: true });
+        }
+    }
+    catch (e) {
+        hardFail("PROJECT_KNOWLEDGE_AUDIT_FAILED", `用户项目知识消费行为审计执行失败: ${e.message}`, ["src/engine/project_knowledge_contract.ts"], "project-knowledge-consumption", "项目知识消费必须有可执行行为门禁", "修复项目知识合同模块和编译产物");
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+    _info("  模板卫生与项目知识消费验证完成");
+}
 async function checkLongTermMechanization(rootDir, hardFail, _info) {
+    try {
+        const matrix = await import("./historical_issue_mechanization_matrix.js");
+        const report = matrix.validateHistoricalIssueMechanizationMatrix?.();
+        if (!report?.passed) {
+            const messages = (report?.findings ?? []).map((finding) => `${finding.code}: ${finding.message}`).join("; ");
+            hardFail("HISTORICAL_FIRST_PRINCIPLES_MATRIX_INCOMPLETE", `历史问题第一性原理机制化矩阵不完整: ${messages || "未知缺口"}`, ["src/engine/historical_issue_mechanization_matrix.ts", "docs/SoloForge-Batch8问题集.md"], "problem-70", "旧复审只统计 mechanized/partial/not，不强制每个历史问题归入长期机制族", "补齐历史问题机制族、生产入口、must-fail/must-pass 和发布门禁");
+        }
+    }
+    catch (e) {
+        hardFail("HISTORICAL_FIRST_PRINCIPLES_MATRIX_EXCEPTION", `历史问题第一性原理矩阵检查异常: ${e.message}`, ["src/engine/historical_issue_mechanization_matrix.ts"], "problem-70", "旧 gate 不执行历史问题矩阵", "修复历史问题机制化矩阵模块");
+    }
     try {
         const health = await import("./mechanism_health_check.js");
         const report = health.runFullHealthCheck(rootDir);
@@ -2567,6 +2942,10 @@ export async function runReleaseReadinessGate(rootDir) {
     beginPhase("诊断码集中治理检查");
     await checkDiagnosticCentralization(rootDir, hardFail);
     endPhase("诊断码集中治理检查");
+    // 21: 模板卫生与用户项目知识消费验证
+    beginPhase("模板卫生与项目知识消费验证");
+    await checkTemplateAndProjectKnowledgeHygiene(rootDir, hardFail, _info);
+    endPhase("模板卫生与项目知识消费验证");
     // 恢复 console.error 和日志器
     console.error = origConsoleError;
     resetLogger();