soloforge 1.1.46 → 1.1.48

package/dist/server/tools/sf_work.js

@@ -12,18 +12,22 @@
  * 持久化：verify 时写 GateRecord
  */
 import { existsSync } from "node:fs";
+import { join } from "node:path";
 import { z } from "zod";
 import { createToolRegistrar } from "./middleware.js";
 import { initializeDomainEngines, ALL_CONTRACTS } from "../../domain/index.js";
 import { DomainRegistry } from "../../domain/registry.js";
 import { GateRecordStore } from "../../core/gate_record_store.js";
+import { AdversarialReviewStore, MAX_REVIEW_ROUNDS, checkConvergence, checkOscillation, diffErrors, countBySeverity, } from "../../core/adversarial_review_store.js";
 import { isTransitionAllowed, detectLoop } from "../../core/domain_transition.js";
-import { checkScope } from "../../core/scope_checker.js";
 import { getFileGitHash } from "../../core/git_utils.js";
-import { loadGatesForDomain, evaluateGate } from "../../gate/gate_engine.js";
+import { loadGatesForDomain, evaluateGate, computeRulesetHash } from "../../gate/gate_engine.js";
 import { resolveConfig } from "../../context/config/resolver.js";
 import { debug } from "../../shared/logger.js";
 import { SF_WORK_ACTIONS } from "../../gate/contracts/tool_actions.js";
+import { CROSS_VALIDATION_ARTIFACT_PATHS } from "../../gate/executors/executors_trace.js";
+import { discoverSourceRoots } from "../../gate/scope_resolver.js";
+import { aggregateMultiSrcHash } from "../../domain/engine_helpers.js";
 /** system_context（greenfield/brownfield）→ SystemType（新系统/老系统）映射 */
 function toSystemType(ctx) {
     return ctx === "brownfield" ? "老系统" : "新系统";
@@ -31,16 +35,20 @@ function toSystemType(ctx) {
 /** sf_work 参数 schema */
 const sfWorkSchema = {
     domain: z.enum(["design", "build", "verify", "operate"]).describe("目标域"),
-    action: z.enum(SF_WORK_ACTIONS).describe("动作：observe=查看状态 / act=获取 prompt / verify=执行门禁"),
+    action: z.enum(SF_WORK_ACTIONS).describe("动作：observe=查看状态 / deliberate=产出前条件研讨（有疑问才触发头脑风暴+第一性原理，无疑问举证一行） / act=获取 prompt / verify=执行门禁 / adversarial_review=对抗审查（per-artifact 单产物 / cross-artifact 跨产物，loop-until-dry 零 error 收敛、多利益方独立对抗）"),
     target: z.string().optional().describe("目标产物 kind（act 时必填）"),
     artifact_path: z.string().optional().describe("产物路径（verify 时指定）"),
+    artifact: z.string().optional().describe("对抗审查指定单产物 kind（adversarial_review per-artifact 模式；不传=cross-artifact 跨产物）"),
+    round: z.number().optional().describe("对抗审查轮次（1=首轮新建会话；>=2=后续轮，须带 review_id + findings）"),
+    review_id: z.string().optional().describe("对抗审查会话 ID（round>=2 必填，首轮返回）"),
+    findings: z.array(z.any()).optional().describe("对抗审查本轮发现（round>=2 客户端结构化提交：[{severity:'error|warning|info', artifact, location, quote, issue, suggestion}]）"),
 };
 // 缓存域引擎注册表（每个 projectRoot 一个）
 const registryCache = new Map();
 export async function registerSfWorkTools(ctx) {
     const { registerSafeTool } = createToolRegistrar(ctx);
     const projectRoot = ctx.projectPath;
-    registerSafeTool("sf_work", "域工作工具。observe：派生当前域状态。act：获取工作 prompt（AI 按此写文件）。verify：执行门禁检查。", sfWorkSchema, async (args) => {
+    registerSafeTool("sf_work", "域工作工具。observe：派生当前域状态。act：获取工作 prompt（AI 按此写文件）。verify：执行门禁检查。adversarial_review：排独立 agent 对抗审查所有产物（产物校验标准环节，不论门禁通过与否）。", sfWorkSchema, async (args) => {
         const domain = args.domain;
         const action = args.action;
         try {
@@ -83,9 +91,15 @@ export async function registerSfWorkTools(ctx) {
             if (action === "observe") {
                 return await handleObserve(engine, task);
             }
+            else if (action === "deliberate") {
+                return await handleDeliberate(engine, task, args, projectRoot);
+            }
             else if (action === "act") {
                 return await handleAct(engine, task, args, projectRoot);
             }
+            else if (action === "adversarial_review") {
+                return await handleAdversarialReview(projectRoot, task, args, taskContext);
+            }
             else {
                 return await handleVerify(engine, task, projectRoot, taskContext, args);
             }
@@ -117,48 +131,189 @@ async function handleObserve(engine, task) {
             verified_artifacts: state.verified_artifacts.map((a) => a.kind),
             missing_upstream: state.missing_upstream,
             stale_gates: state.stale_gates.length,
+            blocked_artifacts: state.blocked_artifacts?.map((b) => ({ artifact: b.artifact.kind, blocked_by: b.blocked_by })),
+            ordered_plan: state.ordered_plan,
             pending_return: state.pending_return,
-            next_step: state.pending_artifacts.length > 0
-                ? `调用 sf_work domain="${state.current_domain}" action="act" target="${state.pending_artifacts[0].kind}"`
-                : state.unverified_artifacts.length > 0
-                    ? `调用 sf_work domain="${state.current_domain}" action="verify"`
-                    : "所有产物已验证通过",
+            next_step: !state.ordered_plan || state.ordered_plan.length === 0
+                ? "所有产物已验证通过"
+                : state.ordered_plan[0].action === "wait"
+                    ? `等待：${state.ordered_plan[0].kind}（${state.ordered_plan[0].reason}）`
+                    : `按 ordered_plan 推进，当前：sf_work domain="${state.current_domain}" action="${state.ordered_plan[0].action}" target="${state.ordered_plan[0].kind}"`,
         },
     };
 }
 /** act：组装 prompt */
-async function handleAct(engine, task, args, projectRoot) {
+export async function handleAct(engine, task, args, projectRoot) {
     const target = args.target;
     if (!target) {
         return { result: { success: false, error: "act 时 target 必填（产物 kind）" } };
     }
+    // target 须是当前域产物（否则 engine.act 抛错，非 graceful）— 门禁前校验，返回可用清单
+    if (!engine.contract.produces.some((a) => a.kind === target)) {
+        return { result: {
+                success: false,
+                error: `「${target}」非本域（${engine.contract.name}）产物。可用：${engine.contract.produces.map((a) => a.kind).join(", ")}`,
+            } };
+    }
+    // 架构决策研讨门禁（仅 design 域；内部 requiresArchitectureDecisionWorkshop 按 intent 判断是否真进，非架构意图自动放行）
+    if (engine.contract.name === "design") {
+        const { checkArchitectureDecisionWorkshopGate } = await import("../../gate/gate_checks.js");
+        const gateResult = await checkArchitectureDecisionWorkshopGate({ ctx: task, workflowIntent: task.intent });
+        if (!gateResult.allowed) {
+            return { result: {
+                    success: false,
+                    error: gateResult.findings?.join("; ") ?? "架构决策研讨门禁未通过",
+                    gate_blocked: true,
+                    recovery_guide: gateResult.recovery_guide_zh,
+                    next_domain: gateResult.next_domain,
+                    next_step: gateResult.recovery_guide_zh
+                        ? `按恢复指引逐域确认。下一个待确认域: ${gateResult.next_domain}，调 sf_task action=confirm_decisions`
+                        : "架构决策研讨未完成",
+                } };
+        }
+    }
+    // ── act 可做性门禁（①②③ 确定性 enforced，复用 observe 派生，闭环「以 ordered_plan 为准」）──
+    // ④ 按序不强制（ordered_plan 仅软指引），避免误伤合法顺序调整
+    const eligibility = await engine.observe(task);
+    // 共用：target 已存在（重写：未验证 Reflexion 修复 / 已验证演进）→ ②③放行
+    //   重写不依赖上游新增（②）、不算并行开新产物（③）
+    const isRewrite = eligibility.unverified_artifacts.some((a) => a.kind === target)
+        || eligibility.verified_artifacts.some((a) => a.kind === target);
+    // ② 跨域缺上游 + 新产物 → 拒（重写放行：Reflexion 修复/演进不依赖上游新增，如 design 未验时 build code 重写修 lazy）
+    if (eligibility.missing_upstream.length > 0 && !isRewrite) {
+        const missing = eligibility.missing_upstream.map((u) => `${u.from_domain}.${u.artifact_kind}`).join("、");
+        return { result: {
+                success: false,
+                gate_blocked: true,
+                error: `本域缺上游产物（${missing}）未通过门禁，不能 act 新产物「${target}」。先回上游域产出并 verify。（重写已有产物不拦：target 传该产物）`,
+                next_step: `先在上游域产出并 verify：${missing}，再回本域 act`,
+            } };
+    }
+    // ① target 被同域依赖阻塞 → 拒（depends_on 未 verify）
+    const blockedBy = eligibility.blocked_artifacts?.find((b) => b.artifact.kind === target)?.blocked_by;
+    if (blockedBy) {
+        return { result: {
+                success: false,
+                gate_blocked: true,
+                error: `产物「${target}」被同域依赖阻塞，需先 verify：${blockedBy.join("、")}`,
+                next_step: `先 sf_work action="verify" 验证：${blockedBy.join("、")}，再 act「${target}」`,
+            } };
+    }
+    // ③ 不并行/不跳步：存在未验证产物且 target 是新产物（pending，非重写）→ 拒（单产物推进）
+    //    target ∈ unverified|verified → 放行（重写：Reflexion 修复 / 已验证演进，单产物迭代不算并行）
+    if (!isRewrite && eligibility.unverified_artifacts.length > 0) {
+        const unverified = eligibility.unverified_artifacts.map((a) => a.kind).join("、");
+        return { result: {
+                success: false,
+                gate_blocked: true,
+                error: `存在未验证产物（${unverified}），先 verify 再 act 新产物（单产物推进，不并行/不跳步）。若要重写产物（未验证修复 / 已验证演进），target 传该产物。`,
+                next_step: `先 sf_work action="verify" 验证：${unverified}`,
+            } };
+    }
+    // ④ 对抗审查不可省（新产物 act 前）：当前域 + 上游域 verified 产物须都有 per_artifact 对抗审查
+    //    enforce 第80行「adversarial_review 独立审查不可省」——防 AI 选择性跳审（如 db/api/slice_plan）
+    //    跨域 act（进 build）时查上游域（design）全 verified，堵每域最后产物漏审
+    //    （design slice_plan 是 design 最后产物，无后续同域 act 触发④，靠跨域 build act 时查上游补）
+    //    isRewrite（重写修复/演进）放行：单产物迭代不算开新产物，不截断 Reflexion（同②③，对称）
+    if (!isRewrite) {
+        const adversarialStore = new AdversarialReviewStore(projectRoot);
+        const reviews = await adversarialStore.listByTask(task.task_id);
+        // converged 收敛 或 escalated 升级人工 都算「审过」（oscillated 震荡未收敛不算，须再审）
+        const reviewedKinds = new Set(reviews.filter((r) => r.mode === "per_artifact" && (r.converged || r.status === "escalated")).map((r) => r.artifact_path));
+        // 需审 verified：当前域 + 上游域（跨域查上游堵最后产物漏审）
+        const domainsToCheck = new Set([engine.contract.name]);
+        for (const req of engine.contract.requires_upstream)
+            domainsToCheck.add(req.from_domain);
+        const reviewRegistry = getOrCreateRegistry(projectRoot);
+        const unreviewed = [];
+        for (const dName of domainsToCheck) {
+            const dEngine = dName === engine.contract.name ? engine : reviewRegistry.get(dName);
+            if (!dEngine)
+                continue;
+            let dState = eligibility;
+            if (dName !== engine.contract.name) {
+                // observe 按 task.domain_focus 取域（observer.deriveState 用 ALL_CONTRACTS + domain_focus），
+                // 查上游域须临时切 domain_focus 到 dName，observe 后恢复（try/finally，单线程无并发）
+                const origDomain = task.domain_focus;
+                task.domain_focus = dName;
+                try {
+                    dState = await dEngine.observe(task);
+                }
+                finally {
+                    task.domain_focus = origDomain;
+                }
+            }
+            for (const a of dState.verified_artifacts) {
+                if (!reviewedKinds.has(a.kind))
+                    unreviewed.push(a.kind);
+            }
+        }
+        if (unreviewed.length > 0) {
+            const unreviewedList = unreviewed.join("、");
+            return { result: {
+                    success: false,
+                    gate_blocked: true,
+                    error: `已验证产物未做 per_artifact 对抗审查：${unreviewedList}。adversarial_review 独立审查不可省（所有域所有产物），先审再推进下一个产物。`,
+                    next_step: `逐个调 sf_work action="adversarial_review" artifact="<kind>" 审：${unreviewedList}`,
+                } };
+        }
+    }
+    // ⑤ cross-artifact 不可省（跨域推进前，上游域所有产物做跨产物独立审查：多利益方独立对抗 + 跨产物一致性 + 完整性 + 研讨充分性）
+    //    触发：!isRewrite（新产物）+ requires_upstream 非空（进下游域 build/verify/operate）。design 域无上游不触发（域内推进）。
+    if (!isRewrite && engine.contract.requires_upstream.length > 0) {
+        const xStore = new AdversarialReviewStore(projectRoot);
+        const xReviews = await xStore.listByTask(task.task_id);
+        const xPerArtifacts = xReviews.filter((r) => r.mode === "per_artifact");
+        const xCrossArtifacts = xReviews.filter((r) => r.mode === "cross_artifact" && (r.converged || r.status === "escalated"));
+        const xCrossLatest = xCrossArtifacts.sort((a, b) => b.updated_at - a.updated_at)[0];
+        if (!xCrossLatest) {
+            return { result: {
+                    success: false,
+                    gate_blocked: true,
+                    error: `跨域推进前须做 cross-artifact 对抗审查（上游域所有产物：多利益方独立对抗 + 跨产物一致性 + 完整性 + 研讨充分性），当前无收敛记录。`,
+                    next_step: `调 sf_work action="adversarial_review"（不传 artifact，cross-artifact 审当前域所有产物），loop-until-dry 零 error 收敛后再推进下一域`,
+                } };
+        }
+        const xLatestPer = xPerArtifacts.sort((a, b) => b.updated_at - a.updated_at)[0];
+        if (xLatestPer && xCrossLatest.updated_at < xLatestPer.updated_at) {
+            return { result: {
+                    success: false,
+                    gate_blocked: true,
+                    error: `cross-artifact 审查已过时（在最新 per-artifact 审查之前）。上游域最新产物产出后须重新 cross-artifact 审。`,
+                    next_step: `调 sf_work action="adversarial_review"（不传 artifact）重审当前域所有产物，收敛后再推进`,
+                } };
+        }
+    }
     // 加载上游产物内容（从文件系统读取真实内容）
     const upstream = await loadUpstreamContent(task, engine, args, projectRoot);
+    // 注入域内研讨记录为上游（deliberate 对话研讨后总结留痕，act 承接研讨结论；研讨记录在 docs/研讨记录/{域中文}/）
+    const actArtifact = engine.contract.produces.find((a) => a.kind === target);
+    if (actArtifact) {
+        const { deliberationRecordPath } = await import("../../domain/engine_helpers.js");
+        const deliberationPath = deliberationRecordPath(engine.contract.name, actArtifact);
+        if (existsSync(join(projectRoot, deliberationPath))) {
+            try {
+                const { readFileSync } = await import("node:fs");
+                const content = readFileSync(join(projectRoot, deliberationPath), "utf-8");
+                upstream["研讨记录"] = content.length > 8000 ? content.slice(0, 8000) + "\n...（研讨记录已截断）" : content;
+            }
+            catch {
+                // 读取失败忽略，act 仍可进行（研讨记录非必需上游）
+            }
+        }
+    }
     // 加载上次验证反馈（Reflexion 闭环：上次 verify 失败的真实 findings → 注入 prompt 让 AI 针对修复）
-    const feedback = await loadLastVerifyFeedback(task, engine.contract.name, projectRoot);
+    // per-产物：只取当前 target 产物的失败记录（修 D8：多产物场景避免返回别的产物 findings 注入错位）
+    const actArtifactPath = engine.contract.produces.find((a) => a.kind === target)?.path_pattern;
+    const feedback = await loadLastVerifyFeedback(task, engine.contract.name, projectRoot, actArtifactPath);
     const result = await engine.act(task, target, upstream, feedback);
     // 注入工程指导（guidance）+ 自评清单
     const { loadGuidance } = await import("../../domain/engine_helpers.js");
-    const guidance = loadGuidance(projectRoot, engine.contract.name, task.intent);
+    const guidance = loadGuidance(projectRoot, engine.contract.name, task.intent, target);
     if (guidance.fullText) {
         result.prompt = result.prompt.replace("## 要求", `## 工程参考\n\n### 本阶段可用经验\n${guidance.summary}\n\n${guidance.fullText}\n\n## 要求`);
     }
     result.self_review_checklist = guidance.checklist;
-    // scope 硬检查：校验 act 返回的 allowed_paths
-    if (result.scope?.allowed_paths && result.scope.allowed_paths.length > 0) {
-        for (const p of result.scope.allowed_paths) {
-            const scopeResult = checkScope(p, result.scope.allowed_paths, result.scope.read_only_paths);
-            if (!scopeResult.allowed) {
-                return {
-                    result: {
-                        success: false,
-                        error: `scope 检查失败：${scopeResult.reason}`,
-                        scope_violation: p,
-                    },
-                };
-            }
-        }
-    }
     return {
         result: {
             success: true,
@@ -170,6 +325,26 @@ async function handleAct(engine, task, args, projectRoot) {
         },
     };
 }
+/** deliberate：组装产出前条件研讨 prompt（有疑问才触发头脑风暴+第一性原理，无疑问举证一行）。
+ *  产出研讨记录到 docs/deliberation/{domain}/{kind}-研讨记录.md，供后续 act 承接。
+ *  SoloForge 不调 LLM——只组装 prompt，AI 自己写研讨记录。 */
+export async function handleDeliberate(engine, task, args, projectRoot) {
+    const target = args.target;
+    if (!target) {
+        return { result: { success: false, error: "deliberate 时 target 必填（产物 kind）" } };
+    }
+    const upstream = await loadUpstreamContent(task, engine, args, projectRoot);
+    const result = await engine.deliberate(task, target, upstream);
+    return {
+        result: {
+            success: true,
+            prompt: result.prompt,
+            template: result.template,
+            scope: result.scope,
+            next_step: `按研讨纪律产出研讨记录（有疑问走四步法、无疑问举证一行），然后调 sf_work action="act" target="${target}" 承接研讨结论产出实际产物`,
+        },
+    };
+}
 /** verify：执行门禁检查并持久化 GateRecord */
 async function handleVerify(engine, task, projectRoot, taskContext, args) {
     const gateStore = new GateRecordStore(projectRoot);
@@ -183,27 +358,40 @@ async function handleVerify(engine, task, projectRoot, taskContext, args) {
         return { result: { success: false, error: "未找到匹配的产物声明" } };
     }
     // 读取已有门禁记录，计算 retry_count
-    const existingRecord = await gateStore.read(domain, artifact.gate);
+    const existingRecord = await gateStore.read(domain, artifact.gate, artifact.path_pattern);
     const retryCount = existingRecord ? existingRecord.retry_count : 0;
     // 检查是否超过重试限制
     if (retryCount >= 5) {
-        // 治本：重试超限升级为业务终态 escalated（原 TaskStore.update({status:escalated})）
-        await taskContext.updateStatus(task.task_id, "escalated");
-        return {
-            result: {
-                success: false,
-                error: `门禁重试次数已达上限（${retryCount}/5），任务已升级处理`,
-            },
-        };
+        // retry 超限：若产物已修复（git hash 变 = stale），允许重验（retry_count 通过时重置，给人工修复后恢复）；
+        // 未修复（hash 同）→ 真超限升级 escalated（防无限重试）。
+        const fullChk = join(projectRoot, artifact.path_pattern);
+        const currentHash = existsSync(fullChk) ? await getFileGitHash(artifact.path_pattern, projectRoot) : "";
+        const fixed = !!existingRecord && existingRecord.artifact_git_hash !== currentHash;
+        if (!fixed) {
+            await taskContext.updateStatus(task.task_id, "escalated");
+            return {
+                result: {
+                    success: false,
+                    error: `门禁重试次数已达上限（${retryCount}/5），任务已升级处理。修复产物（改文件内容使 git hash 变）后重新 verify 可重置计数恢复`,
+                },
+            };
+        }
+        // 已修复 → 继续重验（passed 时 retry_count 写 0 重置，见下）
     }
-    // 检查产物文件是否存在
+    // 检查产物文件是否存在。code 产物（path_pattern=src/）多工程下代码分布在 根/{端}/src/，
+    // 任一工程 src/ 存在即算产出（discoverSourceRoots 探测）；其他产物按精确路径。
     const fullArtifactPath = `${projectRoot}/${artifact.path_pattern}`;
-    const artifactExists = existsSync(fullArtifactPath);
+    const isMultiSrcArtifact = /(^|\/)src\/?$/.test(artifact.path_pattern);
+    const artifactExists = isMultiSrcArtifact
+        ? discoverSourceRoots(projectRoot).length > 0 || existsSync(fullArtifactPath)
+        : existsSync(fullArtifactPath);
     // 获取产物 git hash（防漂移）
     let artifactGitHash = "";
     if (artifactExists) {
         try {
-            artifactGitHash = await getFileGitHash(artifact.path_pattern, projectRoot);
+            artifactGitHash = isMultiSrcArtifact
+                ? await aggregateMultiSrcHash(projectRoot)
+                : await getFileGitHash(artifact.path_pattern, projectRoot);
         }
         catch {
             artifactGitHash = "untracked";
@@ -234,7 +422,16 @@ async function handleVerify(engine, task, projectRoot, taskContext, args) {
                 taskContext: task,
             };
             for (const gate of gates) {
-                const result = await evaluateGate(gate, evalCtx);
+                // per-产物路由：只跑无 required_artifact 的通用 check + 命中当前 verify 产物的专属 check。
+                // 修复 per-域缺陷：此前 verify 任一产物跑整个 domain-gate，逐个产出时前面产物被后面章节检查阻断。
+                const filteredChecks = gate.checks.filter((c) => {
+                    if (!c.required_artifact)
+                        return true;
+                    if (c.required_artifact === artifact.path_pattern)
+                        return true;
+                    return (CROSS_VALIDATION_ARTIFACT_PATHS[c.required_artifact] || []).includes(artifact.path_pattern);
+                });
+                const result = await evaluateGate({ ...gate, checks: filteredChecks }, evalCtx);
                 if (!result.passed) {
                     gatePassed = false;
                     recoverySummary = result.recovery_summary || recoverySummary;
@@ -273,7 +470,32 @@ async function handleVerify(engine, task, projectRoot, taskContext, args) {
             });
         }
     }
+    // 完整性校验（根因治本：所有域所有产物的 references + companion_files 须存在，防引用悬空/附件遗漏）。
+    // 不靠手填 check.evidence_required，从 contract 声明派生——所有域所有产物 verify 时自动全覆盖。
+    const bundleMissing = [];
+    for (const ref of artifact.references ?? []) {
+        if (!existsSync(join(projectRoot, ref)))
+            bundleMissing.push(`引用悬空: ${ref}`);
+    }
+    for (const cf of artifact.companion_files ?? []) {
+        if (!existsSync(join(projectRoot, cf)))
+            bundleMissing.push(`附件缺失: ${cf}`);
+    }
+    for (const m of bundleMissing) {
+        gateFindings.push({
+            check_id: "bundle_integrity",
+            check_name: "产物完整性（引用/附件）",
+            passed: false,
+            severity: "error",
+            message: `产物 ${artifact.kind} ${m}`,
+        });
+        gatePassed = false;
+    }
     const passed = artifactExists && gatePassed;
+    // retry 超限恢复：任务因 retry 5 升级 escalated，人工修复后 verify 通过 → 恢复 executing（继续推进）
+    if (passed && task.status === "escalated") {
+        await taskContext.updateStatus(task.task_id, "executing");
+    }
     // 构建并持久化 GateRecord（task_id 用于 Reflexion 反馈闭环按 task 查询）
     const record = {
         domain: domain,
@@ -282,7 +504,7 @@ async function handleVerify(engine, task, projectRoot, taskContext, args) {
         artifact_path: artifact.path_pattern,
         artifact_git_hash: artifactGitHash,
         passed,
-        retry_count: passed ? retryCount : retryCount + 1,
+        retry_count: passed ? 0 : retryCount + 1, // 通过则重置计数（新一轮），失败累计
         max_retries: 5,
         findings: !artifactExists
             ? [{ check_id: "artifact_exists", check_name: "产物存在性检查", passed: false, severity: "error", message: `产物文件 ${artifact.path_pattern} 不存在` }]
@@ -291,6 +513,7 @@ async function handleVerify(engine, task, projectRoot, taskContext, args) {
             ? `请先调用 sf_work domain="${domain}" action="act" target="${artifact.kind}" 生成产物`
             : (recoverySummary || undefined),
         evaluated_at: Date.now(),
+        ruleset_hash: computeRulesetHash(domain),
     };
     await gateStore.write(record);
     // 治本：检查 pending_return 恢复（通过后才恢复）
@@ -319,12 +542,292 @@ async function handleVerify(engine, task, projectRoot, taskContext, args) {
             gate_record: record,
             retry_count: record.retry_count,
             next_step: passed
-                ? "门禁通过。可继续下一个产物或切换域。"
-                : "门禁未通过。按 recovery_guidance 修复后重新 verify。",
+                ? "门禁通过。建议调 sf_work action=adversarial_review 排独立 agent 对抗复审（产物校验标准环节，全新视角复核，不论门禁通过与否）。复审后再继续下一个产物或切换域。"
+                : "门禁未通过。按 recovery_guidance 修复后重新 verify；修复后建议 sf_work action=adversarial_review 排独立 agent 对抗复审。",
+        },
+    };
+}
+/** adversarial_review：对抗性独立审查（per-artifact 单产物 / cross-artifact 跨产物一致性）。
+ *  SoloForge 不调 LLM——只组装 prompt 返回，AI 用独立 session/subagent 执行（避免确认偏见）。
+ *  loop-until-dry：不限轮数，新一轮零 error 才达标；warning 软收敛记遗留；震荡/超轮熔断升级。
+ *  多利益方独立对抗：用户/攻击者/维护者/性能/合规 各自独立目标函数，避免单一视角确认偏见。 */
+export async function handleAdversarialReview(projectRoot, task, args, taskContext) {
+    const store = new AdversarialReviewStore(projectRoot);
+    const round = typeof args.round === "number" ? args.round : 1;
+    const artifactKind = args.artifact;
+    // ── 首轮：创建会话，组装多利益方审查 prompt ──
+    if (round <= 1) {
+        const mode = artifactKind ? "per_artifact" : "cross_artifact";
+        const artifacts = await collectReviewArtifacts(projectRoot, mode, artifactKind);
+        const reviewId = store.generateReviewId();
+        const now = Date.now();
+        const record = {
+            review_id: reviewId,
+            task_id: task.task_id,
+            mode,
+            artifact_path: mode === "per_artifact" ? artifactKind : undefined, // per_artifact 模式此字段存 artifact **kind**（非文件路径）；④门禁 reviewedKinds 据此比 verified_artifacts.kind——名实澄清（domain/core 审查），改存储格式需同步 ④比较+迁移旧记录
+            artifacts,
+            rounds: [],
+            total_rounds: 0,
+            converged: false,
+            oscillation_detected: false,
+            remaining_warnings: [],
+            status: "in_progress",
+            created_at: now,
+            updated_at: now,
+        };
+        await store.create(record);
+        const prompt = buildReviewPrompt(artifacts, mode, "");
+        return {
+            result: {
+                success: true,
+                action: "adversarial_review",
+                review_id: reviewId,
+                round: 1,
+                mode,
+                review_mode: mode === "per_artifact" ? "per-artifact 单产物深度对抗审查" : "cross-artifact 跨产物一致性对抗审查",
+                artifact_count: artifacts.length,
+                artifacts,
+                prompt,
+                next_step: `用独立 session/subagent 执行上述 prompt（勿在产出产物的同一 session 审查，避免确认偏见）。审查完把 findings 结构化带回：sf_work action="adversarial_review" round=2 review_id="${reviewId}" findings=[{severity,artifact,location,quote,issue,suggestion},...]`,
+            },
+        };
+    }
+    // ── 后续轮：处理 findings，判定收敛/震荡/超轮 ──
+    const reviewId = args.review_id;
+    if (!reviewId) {
+        return { result: { success: false, error: `round=${round} 须带 review_id（首轮返回的会话 ID）` } };
+    }
+    const record = await store.read(reviewId);
+    if (!record) {
+        return { result: { success: false, error: `review_id ${reviewId} 不存在（可能跨会话丢失）` } };
+    }
+    const findings = normalizeFindings(args.findings);
+    const prevRound = record.rounds[record.rounds.length - 1];
+    const { new_errors, fixed_errors } = diffErrors(prevRound, findings);
+    const { error_count, warning_count } = countBySeverity(findings);
+    const roundRecord = {
+        round,
+        findings,
+        error_count,
+        warning_count,
+        new_errors,
+        fixed_errors,
+        reviewed_at: Date.now(),
+    };
+    record.rounds.push(roundRecord);
+    record.total_rounds = round;
+    record.updated_at = Date.now();
+    // 收敛达标（连续一轮零 error；warning 软收敛记遗留）
+    if (checkConvergence(record.rounds)) {
+        record.status = "converged";
+        record.converged = true;
+        record.converged_round = round;
+        record.remaining_warnings = findings.filter((f) => f.severity === "warning");
+        await store.write(record);
+        return {
+            result: {
+                success: true,
+                action: "adversarial_review",
+                review_id: reviewId,
+                round,
+                review_status: "converged",
+                round_summary: { errors: error_count, warnings: warning_count, new_errors, fixed_errors },
+                remaining_warnings: record.remaining_warnings.length,
+                converged: true,
+                next_step: `对抗审查达标（连续一轮零 error）。${record.remaining_warnings.length} 个 warning 记为遗留项（软收敛，不阻断交付）。可继续下一产物或切换域。`,
+            },
+        };
+    }
+    // 震荡熔断（连续多轮修一个引入一个，问题集合不收敛）
+    if (checkOscillation(record.rounds)) {
+        record.status = "oscillated";
+        record.oscillation_detected = true;
+        record.oscillation_round = round;
+        await store.write(record);
+        await taskContext.updateStatus(task.task_id, "escalated");
+        return {
+            result: {
+                success: false,
+                action: "adversarial_review",
+                review_id: reviewId,
+                round,
+                review_status: "oscillated",
+                round_summary: { errors: error_count, warnings: warning_count, new_errors, fixed_errors },
+                next_step: "检测到震荡（连续多轮修一个引入一个，问题集合不收敛），任务已升级处理。建议人工介入排查根因。",
+            },
+        };
+    }
+    // 超轮次兜底（对齐 verify max_retries=5）
+    if (round >= MAX_REVIEW_ROUNDS) {
+        record.status = "escalated";
+        await store.write(record);
+        await taskContext.updateStatus(task.task_id, "escalated");
+        return {
+            result: {
+                success: false,
+                action: "adversarial_review",
+                review_id: reviewId,
+                round,
+                review_status: "escalated",
+                round_summary: { errors: error_count, warnings: warning_count, new_errors, fixed_errors },
+                next_step: `已达轮次上限（${MAX_REVIEW_ROUNDS}）仍有 ${error_count} 个 error 未清零，任务已升级处理。建议人工介入。`,
+            },
+        };
+    }
+    // 继续：注入上轮 findings 反馈，组装下一轮 prompt（Reflexion 模式）
+    await store.write(record);
+    const prompt = buildReviewPrompt(record.artifacts, record.mode, formatRoundFeedback(roundRecord));
+    return {
+        result: {
+            success: true,
+            action: "adversarial_review",
+            review_id: reviewId,
+            round,
+            review_status: "in_progress",
+            round_summary: { errors: error_count, warnings: warning_count, new_errors, fixed_errors },
+            prompt,
+            next_step: `本轮仍有 ${error_count} 个 error 未达标。修复后继续：sf_work action="adversarial_review" round=${round + 1} review_id="${reviewId}" findings=[...]`,
         },
     };
 }
-/** 加载上游产物内容（从文件系统读取） */
+/** 收集审查产物：per=指定单产物 / cross=所有域所有已产出 docs/ 产物；二者都额外收集研讨记录（审查充分性维度） */
+async function collectReviewArtifacts(projectRoot, mode, artifactKind) {
+    const artifacts = [];
+    if (mode === "per_artifact" && artifactKind) {
+        for (const c of ALL_CONTRACTS) {
+            const p = c.produces.find((a) => a.kind === artifactKind);
+            if (p && p.path_pattern.startsWith("docs/") && existsSync(join(projectRoot, p.path_pattern))) {
+                artifacts.push(`${p.path_pattern}（${c.name}/${p.kind}）`);
+            }
+        }
+    }
+    else {
+        for (const c of ALL_CONTRACTS) {
+            for (const p of c.produces) {
+                if (!p.path_pattern.startsWith("docs/"))
+                    continue;
+                if (existsSync(join(projectRoot, p.path_pattern))) {
+                    artifacts.push(`${p.path_pattern}（${c.name}/${p.kind}）`);
+                }
+            }
+        }
+    }
+    // 研讨记录（docs/deliberation/）：审查"研讨充分性"维度——产物决策是否真承接研讨结论
+    await collectDeliberationRecords(projectRoot, artifacts);
+    return artifacts;
+}
+/** 扫描 docs/deliberation/ 收集研讨记录（条件触发的研讨留痕，cross 审查复核充分性） */
+async function collectDeliberationRecords(projectRoot, artifacts) {
+    const { readdirSync, statSync } = await import("node:fs");
+    const root = join(projectRoot, "docs", "研讨记录");
+    if (!existsSync(root))
+        return;
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir)) {
+            const full = join(dir, entry);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else if (entry.endsWith(".md")) {
+                const rel = full.replace(join(projectRoot) + "/", "");
+                artifacts.push(`${rel}（研讨记录）`);
+            }
+        }
+    };
+    walk(root);
+}
+/** 组装多利益方独立对抗审查 prompt。
+ *  5 方（用户/攻击者/维护者/性能/合规）各自独立目标函数，审查前不得互参，最后交叉汇总。
+ *  loop-until-dry 收敛语义写进 prompt：连续一轮零 error 才达标。 */
+function buildReviewPrompt(artifacts, mode, prevFeedback) {
+    const modeLabel = mode === "per_artifact" ? "per-artifact 单产物深度" : "cross-artifact 跨产物一致性";
+    const extraDim = mode === "cross_artifact"
+        ? `### 跨产物一致性（cross 专项）
+- REQ→API→测试 覆盖链是否**语义**对齐（不只 ID 在，而是意图满足；确定性 cross_validation 只抓 ID/字段名，语义层矛盾只有你能抓）
+- 同一事物跨产物描述是否一致（需求 vs 架构 vs API vs 数据库）
+- **完整性方审查**：REQ→API→DB→切片→代码 全链路覆盖——每个 REQ 有对应 API？每个 API 操作的表在 DB 存在？每个 API 有代码方法实现？有无遗漏致业务断裂？
+- **前端承接完整性**（涉及 FE-* 时）：架构 §6.3 每个 FE-* 端有骨架切片？骨架切片落地了路由/状态/API service 壳/认证拦截器？前端各端覆盖需求 §9 声明的所有端？前后端 API 契约一致？
+- **研讨记录充分性**：复杂产物的研讨记录（docs/deliberation/）若全是"无疑问一行举证"——质疑：这个点真无疑问吗？产出是否真承接研讨结论？`
+        : `### 单产物内部深度（per 专项）
+- 该产物内部逻辑自洽、章节完整、无空章节/TODO/占位符
+- 按产物类型重点关注：API 文档→字段映射与 schema 对齐；架构→决策依据/回滚/兼容；测试→REQ 覆盖/可执行性`;
+    const feedbackSection = prevFeedback
+        ? `\n## ⚠️ 上轮审查发现（必须先验证是否已修复，再继续找新问题）\n${prevFeedback}\n`
+        : "";
+    return `# 对抗性独立审查（${modeLabel}，loop-until-dry）
+
+你是**独立审查 agent**，与产物创建 agent 完全隔离（不同 session、全新视角）。**默认所有产物有问题**，禁止说"看起来没问题"。每条发现必须 \`quote\` 引用原文——空泛=凑数=无效，会被丢弃。
+
+## 审查范围
+${artifacts.length > 0 ? artifacts.map((a) => `- \`${a}\``).join("\n") : "（暂无已产出产物，先产出再审查，本轮返回空 findings）"}
+
+## 多利益方独立对抗（每方独立审查，审查前不得参考他方结论，最后才交叉汇总）
+
+### 用户方审查
+根本需求是否被承接？REQ→产物 覆盖链是否语义对齐（需求 → 实现 的意图满足）？
+
+### 攻击者方审查
+越权 / 注入 / 路径穿越 / 敏感信息泄露 / 破坏性操作无确认？
+
+### 维护者方审查
+可读性 / 可改性 / 技术债 / 未接入主链路的孤岛 / 空章节 / TODO？
+
+### 性能方审查
+N+1 / 瓶颈 / 资源泄漏 / 锁竞争 / 扩展性？
+
+### 合规方审查
+规范一致性 / 隐私 / 回滚方案 / 字段契约对齐 / 破坏性变更确认？
+
+### 前端架构方审查（涉及 FE-* 时）
+骨架完整性（路由/状态/组件分层/API service 壳）？前端权限承接后端 RBAC？前后端 API 契约一致？多端 shared 边界清晰？状态管理合理？
+
+${extraDim}
+${feedbackSection}
+## 收敛规则（loop-until-dry）
+- 本轮发现 error 级 → 修复后继续下一轮；**连续一整轮零 error 才达标**（warning/info 不阻断，记遗留）
+- 禁止凑数提前停，禁止为省事放过 error，禁止用 warning 冒充 error 凑数
+
+## 输出格式（严格 JSON 数组，引擎据此判定收敛）
+\`\`\`json
+[
+  {"severity":"error|warning|info","artifact":"产物路径","location":"章节/行","quote":"引用原文","issue":"问题","suggestion":"修复建议"}
+]
+\`\`\`
+- 无问题也必须返回 \`[]\`（这是达标的信号，不是"没问题"四个字）
+- error 优先，按 severity 排序`;
+}
+/** 格式化上轮 findings 为反馈文本（Reflexion：上轮发现 → 注入下轮 prompt 针对性复核） */
+function formatRoundFeedback(round) {
+    if (round.findings.length === 0)
+        return "";
+    const lines = round.findings.map((f) => `- [${f.severity}] ${f.artifact} ${f.location}：${f.issue}${f.suggestion ? ` → 建议：${f.suggestion}` : ""}`);
+    return `第 ${round.round} 轮发现 ${round.error_count} error / ${round.warning_count} warning：\n${lines.join("\n")}`;
+}
+/** 规范化客户端提交的 findings（容错：校验 severity + 补全字符串字段 + 过滤无效条目） */
+function normalizeFindings(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const findings = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object")
+            continue;
+        const f = item;
+        const severity = f.severity;
+        if (severity !== "error" && severity !== "warning" && severity !== "info")
+            continue;
+        findings.push({
+            severity,
+            artifact: String(f.artifact ?? ""),
+            location: String(f.location ?? ""),
+            quote: String(f.quote ?? ""),
+            issue: String(f.issue ?? ""),
+            suggestion: String(f.suggestion ?? ""),
+        });
+    }
+    return findings;
+}
+/** 加载上游产物内容（从文件系统读取真实内容） */
 async function loadUpstreamContent(task, engine, _args, projectRoot) {
     const upstream = {};
     const { readFileSync } = await import("node:fs");
@@ -370,9 +873,9 @@ async function loadUpstreamContent(task, engine, _args, projectRoot) {
  * 无失败记录 / findings 为空 → 返回空串（首次执行或上次通过，无需反馈）。
  * 截断策略与 loadUpstreamContent 一致（8000 字符），避免 prompt 膨胀。
  */
-async function loadLastVerifyFeedback(task, domain, projectRoot) {
+async function loadLastVerifyFeedback(task, domain, projectRoot, artifactPath) {
     const gateStore = new GateRecordStore(projectRoot);
-    const record = await gateStore.readLatestFailed(domain, task.task_id);
+    const record = await gateStore.readLatestFailed(domain, task.task_id, artifactPath);
     if (!record || record.findings.length === 0)
         return "";
     const parts = [];