@zhushanwen/pi-subagent-workflow 4.0.0 → 5.0.0-dev.1

package/workflows/review-fix-loop.js

@@ -13,48 +13,75 @@
 // ⚠️ 唯一带写操作的内置 workflow：fix 阶段会修改文件（autoCommit=true 时 commit）。
 // ⚠️ lintScript 约束（本脚本已遵守）：含 parallel() 入口，禁止 bare IIFE；
 //    agent() 调用顺序确定（批次按配置顺序稳定排序，callId 重放安全）。
+//
+// ⚠️ 与 main 的 4.0.0 版分叉（merge 时 add/add 冲突，刻意决策记录）：
+//    本版（feat-recursive-optimize）保留——纯函数拆到 review-fix-loop-utils.cjs（vitest 覆盖）、
+//    支持 fallow-scan 前置批次、无默认批次（batch1..batchN/agents 必传）、recheckAfterFix 默认 false。
+//    main 4.0.0 版自包含 677 行、缺批次参数时默认单批 ["reviewer"]、recheckAfterFix 默认 false。
+//    merge 时保留本版（功能更全），详见 .changeset/tidy-waves-description-phase-lint.md。
 
 const meta = {
   name: "review-fix-loop",
-  description: "审查-修复循环：多批串行（批内并行 review → aggregate → fix → 重审直到 clean）。必填 targetType（git-diff/file/dir/text）+ target。批次由 batch1..batchN 控制（如 batch1=fallow-scan batch2=reviewer），用于前置检查先行的场景。注意：唯一带写操作/commit 副作用的内置 workflow，autoCommit 默认 false。",
-  phases: [
-    { title: "Review", detail: "Batch: parallel review by configured agents" },
-    { title: "Fix", detail: "Fix must-fix issues from aggregated report" },
-  ],
+  description: "审查-修复循环：多批串行（批内并行 review → aggregate → fix → 重审直到 clean）。必填 targetType（git-diff/file/dir/text）+ target。批次由 batch1..batchN 控制（如 batch1=fallow-scan batch2=reviewer），用于前置检查先行的场景。注意：唯一带写操作/commit 副作用的内置 workflow，autoCommit 默认 false；skipCleanAgents 默认 true + recheckAfterFix 默认 false（clean agent 下轮跳过，与字面语义一致）；传 recheckAfterFix=true 启用可选强回归模式（fix 后重派全批，clean agent 走限定 prompt 只审改动文件）。可选 fixAgent/maxFixAttempts/convergeNewIssues/convergeRounds 控制修复 agent 与收敛终止（详见 workflows/README.md）。",
+  phases: ["Review", "Fix"],
 };
 
 // ── 参数解析 + 白名单校验（fail-fast） ────────────────────────────
 
-const TARGET_TYPES = ["git-diff", "file", "dir", "text"];
-const VALID_ARG_KEYS = new Set([
-  "targetType", "target", "agents", "batchNames", "reviewPrompt", "fixPrompt",
-  "autoCommit", "maxRounds", "stuckThreshold", "model", "skipCleanAgents",
-  "recheckAfterFix", "_runId",
-]);
-
 function fail(msg) {
   throw new Error("review-fix-loop: " + msg);
 }
 
-function normalizeBool(v, name, def) {
-  if (v === undefined || v === null || v === "") return def;
-  if (v === true || v === "true") return true;
-  if (v === false || v === "false") return false;
-  fail("参数 " + name + " 必须是布尔值（true/false），实际: " + JSON.stringify(v));
-}
-
-function normalizeInt(v, name, def) {
-  if (v === undefined || v === null || v === "") return def;
-  const n = typeof v === "number" ? v : Number(String(v).trim());
-  if (!Number.isInteger(n) || n <= 0) fail("参数 " + name + " 必须是正整数，实际: " + JSON.stringify(v));
-  return n;
-}
+// ── 可测纯函数模块 ────────────────────────────────────────────────
+// 参数校验（normalizeBool/normalizeInt/白名单）/批次解析/聚合结果解析/审查指令构建
+// 的纯函数在 review-fix-loop-utils.cjs（与 recursive-split-utils.cjs 同款模式，
+// vitest 单测见 src/__tests__/review-fix-loop-utils.test.ts）。
+// worker 运行时经 workerData.scriptPath 定位自身目录——内置 workflow 在 npm 包内，
+// process.cwd() 是用户项目目录，不能作为锚点；其他引擎无 workerData 时回退 cwd。
+const {
+  TARGET_TYPES,
+  VALID_ARG_KEYS,
+  normalizeBool,
+  normalizeInt,
+  parseBatches,
+  resolveBatchNames,
+  validateFallowScan,
+  buildReviewInstruction,
+  lockReviewBase,
+  buildScopedRecheckPrompt,
+  wrapUntrusted,
+  buildFixPrompt,
+  buildR2ReviewPrompt,
+  buildAggregatorPrompt,
+  resolveReviewReportPath,
+  normalizeFixResult,
+  validateFixResult,
+  reconcileIssues,
+  normalizeReviewResult,
+  computeKnownRemaining,
+  checkConvergence,
+  findNeedsRedesign,
+  parseResult,
+  normalizeAggregatorResult,
+  parseAggregatedMd,
+  shouldRetryWithReviewPrefix,
+  resolveAgentDefs,
+  recordAgentClean,
+  recordAgentDirty,
+  shouldSkipAgent,
+  updateStuckState,
+  resolveBatchTerminated,
+} = require(
+  (typeof workerData !== "undefined" && workerData && typeof workerData.scriptPath === "string"
+    ? require("path").dirname(workerData.scriptPath)
+    : process.cwd()) + "/review-fix-loop-utils.cjs"
+);
 
 // 白名单校验：未知参数名（防 batchX 拼错如 batchl）→ 报错
 for (const key of Object.keys($ARGS)) {
   if (VALID_ARG_KEYS.has(key)) continue;
   if (/^batch\d+$/.test(key)) continue;
-  fail("未知参数: " + key + "（合法参数: targetType/target/batch1..batchN/agents/batchNames/reviewPrompt/fixPrompt/autoCommit/maxRounds/stuckThreshold/model/skipCleanAgents/recheckAfterFix）");
+  fail("未知参数: " + key + "（合法参数: targetType/target/batch1..batchN/agents/batchNames/reviewPrompt/fixPrompt/autoCommit/maxRounds/stuckThreshold/model/skipCleanAgents/recheckAfterFix/fixAgent/maxFixAttempts/convergeNewIssues/convergeRounds）");
 }
 
 const targetType = $ARGS.targetType;
@@ -70,77 +97,52 @@ const reviewPrompt = typeof $ARGS.reviewPrompt === "string" && $ARGS.reviewPromp
 const fixPrompt = typeof $ARGS.fixPrompt === "string" && $ARGS.fixPrompt.trim()
   ? $ARGS.fixPrompt.trim()
   : "修复全部 must-fix 问题（critical/major）。最小正确修复，不做重构、不做风格改动。";
-const autoCommit = normalizeBool($ARGS.autoCommit, "autoCommit", false);
-const maxRounds = normalizeInt($ARGS.maxRounds, "maxRounds", 10);
-const stuckThreshold = normalizeInt($ARGS.stuckThreshold, "stuckThreshold", 3);
-const skipCleanAgents = normalizeBool($ARGS.skipCleanAgents, "skipCleanAgents", true);
-const recheckAfterFix = normalizeBool($ARGS.recheckAfterFix, "recheckAfterFix", false);
+const autoCommit = normalizeBool($ARGS.autoCommit, "autoCommit", false, fail);
+const maxRounds = normalizeInt($ARGS.maxRounds, "maxRounds", 10, fail);
+const stuckThreshold = normalizeInt($ARGS.stuckThreshold, "stuckThreshold", 3, fail);
+const skipCleanAgents = normalizeBool($ARGS.skipCleanAgents, "skipCleanAgents", true, fail);
+// 默认 recheckAfterFix=false：clean agent 下轮跳过（与 skipCleanAgents=true 字面语义一致），
+// RC-5（fix 后全批全量重审放大 token）在默认场景消失。传 true 启用可选强回归模式：fix 后重派
+// 全批，clean agent 走限定 prompt（buildScopedRecheckPrompt，只审 modifiedFiles，5.5）。
+const recheckAfterFix = normalizeBool($ARGS.recheckAfterFix, "recheckAfterFix", false, fail);
+// fixAgent（5.3）：值语义同 batchN 的 agent 项（内置名 / agent.md 路径），解析复用
+// resolveAgentDefs 白名单与加载逻辑。传入时 fix 阶段用 agent({agent: ...}) 派发（代码场景
+// 的 verify 命令写在该 agent.md 内）；未传保持现状（通用 subagent + 内联 prompt）。
+const FIX_AGENT_RAW = typeof $ARGS.fixAgent === "string" && $ARGS.fixAgent.trim()
+  ? $ARGS.fixAgent.trim() : undefined;
+const FIX_DEF = FIX_AGENT_RAW ? resolveAgentDefs([FIX_AGENT_RAW])[0] : null;
+// 5.7 收敛终止参数：maxFixAttempts（needs-redesign 阈值，RC-7）/ convergeNewIssues +
+// convergeRounds（新发现率收敛阈值）
+const maxFixAttempts = normalizeInt($ARGS.maxFixAttempts, "maxFixAttempts", 2, fail);
+const convergeNewIssues = normalizeInt($ARGS.convergeNewIssues, "convergeNewIssues", 1, fail);
+const convergeRounds = normalizeInt($ARGS.convergeRounds, "convergeRounds", 2, fail);
 const MODEL = typeof $ARGS.model === "string" && $ARGS.model.trim() ? $ARGS.model.trim() : undefined;
 
-// 审查指令模板（按 targetType 生成，注入每个 review agent 的 prompt）
-function buildReviewInstruction() {
-  switch (targetType) {
-    case "git-diff":
-      return "Review `git diff " + target + "...HEAD` for all committed changes against " + target + ".\n" +
-        "ALSO run `git status --porcelain` and `git diff` to review uncommitted working-tree changes " +
-        "(fixes may be uncommitted when autoCommit=false; uncommitted changes ARE in scope).";
-    case "file":
-      return "Read and review the file: " + target;
-    case "dir":
-      return "Explore and review the directory: " + target + " (list files, then read the relevant ones)";
-    case "text":
-      return "Review target: " + target;
-  }
-}
-const reviewInstruction = buildReviewInstruction();
-
-// 批次解析：batch1..batchN（缺号报错）/ agents 简写 / 默认单批 [reviewer]
-function parseBatches() {
-  const batchKeys = Object.keys($ARGS)
-    .filter((k) => /^batch\d+$/.test(k))
-    .sort((a, b) => parseInt(a.slice(5), 10) - parseInt(b.slice(5), 10));
-  const nums = batchKeys.map((k) => parseInt(k.slice(5), 10));
-  for (let i = 1; i <= nums.length; i++) {
-    if (!nums.includes(i)) fail("批次参数缺号：有 batch" + nums.join("/") + " 但无 batch" + i + "（批次必须连续编号）");
-  }
-  if ($ARGS.agents !== undefined && $ARGS.batch1 !== undefined) {
-    fail("agents 与 batch1 不能同时传（agents 是单批简写）");
-  }
-
-  let rawBatches;
-  if (batchKeys.length > 0) {
-    rawBatches = batchKeys.map((k) => $ARGS[k]);
-  } else if ($ARGS.agents !== undefined) {
-    rawBatches = [$ARGS.agents];
+// base 锁定（RC-6，5.6）：git-diff 场景 run 启动时锁定 base commit，全程用锁定 hash 构造
+// diff 指令，防止 run 期间 base ref 被更新导致各轮 diff 范围不一致。rev-parse 失败（非 git
+// 目录 / ref 不存在）降级用原 ref 并 warn，锁定结果随 state.meta.baseHash 记录。
+const lockedBase = lockReviewBase(targetType, target);
+if (targetType === "git-diff") {
+  if (lockedBase.hash) {
+    log("Locked review base: " + target + " -> " + lockedBase.hash);
   } else {
-    rawBatches = ["reviewer"]; // 默认单批：包内置通用审查 agent
+    log("WARN: git rev-parse " + target + " failed, falling back to ref for diff base: " + target);
   }
-
-  return rawBatches.map((raw, idx) => {
-    if (typeof raw !== "string" || !raw.trim()) fail("batch" + (idx + 1) + " 不能为空");
-    const names = raw.split(",").map((s) => s.trim()).filter(Boolean);
-    if (names.length === 0) fail("batch" + (idx + 1) + " 为空（逗号分隔 agent 名/文件路径）");
-    if (new Set(names).size !== names.length) fail("batch" + (idx + 1) + " 内存在重复 agent: " + names);
-    return names;
-  });
 }
-const BATCHES = parseBatches();
+const reviewInstruction = buildReviewInstruction(targetType, lockedBase.base);
+
+// 批次解析：batch1..batchN（缺号报错）/ agents 简写；无默认批次——缺批次参数时
+// parseBatches 直接 fail-fast（与头注释「batch1..batchN/agents 必传」一致）
+const BATCHES = parseBatches($ARGS, fail);
 
 // batchNames（数量校验）
 const rawBatchNames = typeof $ARGS.batchNames === "string" && $ARGS.batchNames.trim()
   ? $ARGS.batchNames.split(",").map((s) => s.trim()).filter(Boolean)
   : [];
-if (rawBatchNames.length > 0 && rawBatchNames.length !== BATCHES.length) {
-  fail("batchNames 数量（" + rawBatchNames.length + "）必须与批数（" + BATCHES.length + "）一致");
-}
-const BATCH_NAMES = rawBatchNames.length ? rawBatchNames : BATCHES.map((_, i) => "batch-" + (i + 1));
+const BATCH_NAMES = resolveBatchNames(rawBatchNames, BATCHES, fail);
 
 // fallow-scan 只在 git-diff 类型下有意义
-for (let i = 0; i < BATCHES.length; i++) {
-  if (BATCHES[i].includes("fallow-scan") && targetType !== "git-diff") {
-    fail("fallow-scan 只支持 targetType=git-diff（它审查 git 变更的静态分析），实际 targetType=" + targetType);
-  }
-}
+validateFallowScan(BATCHES, targetType, fail);
 
 // ── Schemas ─────────────────────────────────────────────────────────
 
@@ -148,8 +150,22 @@ const reviewerSchema = {
   type: "object",
   properties: {
     report_file: { type: "string", description: "Absolute path to the written review report (.md)" },
+    report_content: { type: "string", description: "Full markdown report body (for schema-only agents without write tool; workflow writes it to <roundDir>/<report>.md)" },
     must_fix: { type: "number", description: "Number of must-fix (critical+major) issues found" },
     suggestion: { type: "number", description: "Number of suggestion-level (minor) issues found" },
+    reconciliation: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          prev_id: { type: "string", description: "Issue id from the previous round (reconciliation continuation)" },
+          status: { type: "string", description: "fixed / not-fixed / regressed / escalate — only fixed counts as resolved; fix result claiming fixed is NOT evidence; escalate = a DEFERRED issue whose context was changed by this round's fix (workflow re-opens it for fixing)" },
+          evidence: { type: "string", description: "What was read/confirmed (file + what changed)" },
+        },
+        required: ["prev_id", "status"],
+      },
+      description: "R2+ reconciliation table (structured): MANDATORY for R2+ rounds, optional for R1",
+    },
   },
   required: ["report_file", "must_fix", "suggestion"],
 };
@@ -160,10 +176,69 @@ const aggregatorSchema = {
     report_file: { type: "string", description: "Absolute path to aggregated.md" },
     must_fix: { type: "number", description: "Total must-fix after dedup across all dimensions" },
     suggestion: { type: "number", description: "Total suggestions after dedup across all dimensions" },
+    must_fix_ids: {
+      type: "array",
+      // M1: 支持 [{id, severity}] 对象（severity: critical/major/minor——converged 终止的
+      // 「无 critical」判定数据源）+ 旧格式 string[] 兼容。ajv 权威校验两者皆放行。
+      items: {
+        oneOf: [
+          { type: "string" },
+          {
+            type: "object",
+            required: ["id"],
+            properties: {
+              id: { type: "string" },
+              severity: { type: "string" },
+            },
+          },
+        ],
+      },
+      description: "Issue ids of the deduplicated must-fix list (MF-1..N), matching the first column of the markdown table",
+    },
+    fixes_caution: {
+      type: "array",
+      items: { type: "string" },
+      description: "Caution entries for weak-evidence or high-risk claims (passed to fix stage)",
+    },
   },
   required: ["report_file", "must_fix", "suggestion"],
 };
 
+// fix schema（5.3）：object[]（issue_id/description/self_check/affected_files）+ deferred。
+// 兼容性：normalizeFixResult 对旧格式（fixes string[]、无 deferred）兜底解析。
+const fixSchema = {
+  type: "object",
+  properties: {
+    fixed_count: { type: "number", description: "Number of issues fixed" },
+    fixes: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          issue_id: { type: "string", description: "Issue identifier from the aggregated report" },
+          description: { type: "string", description: "One-line description of the fix" },
+          self_check: { type: "string", description: "grep command + hit count + sync action proving the fix is complete" },
+          affected_files: { type: "array", items: { type: "string" }, description: "Files touched by this fix + files checked/synced as reference points" },
+        },
+        // m3: issue_id 是 ES3 交叉校验（must-fix 必须全进 fixes[]）的匹配键，必填
+        required: ["issue_id"],
+      },
+    },
+    deferred: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          issue_id: { type: "string" },
+          severity: { type: "string", description: "Must be minor — critical/major must not be deferred" },
+          reason: { type: "string", description: "Concrete cost description: which files/mechanisms involved, why high cost, suggested follow-up" },
+        },
+      },
+    },
+  },
+  required: ["fixed_count"],
+};
+
 // ── Per-run isolation: runId-scoped directories ─────────────────────
 
 const fs = require("fs");
@@ -191,6 +266,11 @@ function loadState() {
       agentStatus: {},
       fixCount: 0,
       batches: [],
+      fixResults: [],
+      issues: undefined,
+      knownRemaining: [],
+      convergeStreak: 0,
+      lastModifiedFiles: [],
     };
   }
 }
@@ -201,112 +281,29 @@ function saveState(state) {
   fs.renameSync(tmp, STATE_FILE);
 }
 
-// clean 记录：lastCleanBatch + 当时全局 fixCount 快照（跨批跳过判定依据）
-function recordAgentClean(state, agentName, batchIndex) {
-  const s = state.agentStatus[agentName] || { lastCleanBatch: 0, lastCleanFixCount: 0, lastActiveRound: 0, lastMustFix: undefined };
-  s.lastCleanBatch = batchIndex;
-  s.lastCleanFixCount = state.fixCount;
-  s.lastActiveRound = batchIndex;
-  state.agentStatus[agentName] = s;
-}
-
-function recordAgentDirty(state, agentName, mustFix, batchIndex) {
-  const s = state.agentStatus[agentName] || { lastCleanBatch: 0, lastCleanFixCount: 0, lastActiveRound: 0, lastMustFix: undefined };
-  s.lastActiveRound = batchIndex;
-  s.lastMustFix = mustFix;
-  state.agentStatus[agentName] = s;
-}
-
-// ── Helpers ─────────────────────────────────────────────────────────
-
-function parseResult(raw) {
-  if (typeof raw === "object" && raw !== null) return raw;
-  if (typeof raw === "string") {
-    let s = raw.trim();
-    const fence = s.match(/^```(?:json)?\s*\n([\s\S]*?)\n?```\s*$/i);
-    if (fence) s = fence[1].trim();
-    if (!s.startsWith("{") && !s.startsWith("[")) {
-      const first = s.indexOf("{");
-      const last = s.lastIndexOf("}");
-      if (first !== -1 && last > first) s = s.slice(first, last + 1);
-    }
-    try { return JSON.parse(s); } catch { /* fall through */ }
-  }
-  return null;
-}
+// clean 记录（recordAgentClean/recordAgentDirty 与跨批跳过判定 shouldSkipAgent
+// 在 review-fix-loop-utils.cjs，vitest 单测见 src/__tests__/review-fix-loop-utils.test.ts）
 
-function normalizeAggregatorResult(raw) {
-  const parsed = parseResult(raw);
-  if (!parsed) return null;
-  const mustFix =
-    typeof parsed.must_fix === "number" ? parsed.must_fix :
-    typeof parsed.totalMustFix === "number" ? parsed.totalMustFix :
-    typeof parsed.mustFix === "number" ? parsed.mustFix : undefined;
-  const suggestion =
-    typeof parsed.suggestion === "number" ? parsed.suggestion :
-    typeof parsed.totalSuggestions === "number" ? parsed.totalSuggestions :
-    typeof parsed.suggestions === "number" ? parsed.suggestions : 0;
-  if (typeof mustFix !== "number") return null;
-  return { report_file: parsed.report_file || parsed.reportFile, must_fix: mustFix, suggestion };
-}
+// ── Agent defs（loadAgentMd/resolveAgentDefs 在 review-fix-loop-utils.cjs） ──
 
-function parseAggregatedMd(content) {
-  const mustFixMatch = content.match(/[-*]\s*Must[-_]fix\s*[:：]\s*(\d+)/i);
-  if (!mustFixMatch) return null;
-  const suggestionMatch = content.match(/[-*]\s*Suggestions?\s*[:：]\s*(\d+)/i);
-  return {
-    must_fix: parseInt(mustFixMatch[1], 10),
-    suggestion: suggestionMatch ? parseInt(suggestionMatch[1], 10) : 0,
-  };
-}
+// ── Build review calls ──────────────────────────────────────────────
 
-// 自定义 .md agent 加载：frontmatter（name/description/model）+ 正文
-function loadAgentMd(filePath) {
-  let content;
-  try {
-    content = fs.readFileSync(filePath, "utf-8");
-  } catch (e) {
-    fail("agent 文件读取失败: " + filePath + " (" + e.message + ")");
+// 上一轮 fix 的 modifiedFiles（git diff 实测，fix 阶段写入 batchRounds）。
+// recheck 限定 prompt（scoped）的 scope 来源（初版 = modifiedFiles）。
+function lastModifiedFiles() {
+  // M4: 批内轮次循环中 state.batches 尚未 push（仅在终止/批结束 push）——scoped 分支
+  // （recheckAfterFix=true 的下轮 review）执行时读不到本批数据。fix 阶段把
+  // modifiedFiles 同步写入 state.lastModifiedFiles（即时字段，批内立即可用），
+  // 此处优先读它；fallback 旧路径（跨批场景）。
+  if (state.lastModifiedFiles && Array.isArray(state.lastModifiedFiles)) {
+    return state.lastModifiedFiles;
   }
-  let name = path.basename(filePath, ".md");
-  let model, description;
-  let body = content.trim();
-  if (content.startsWith("---")) {
-    const closeIdx = content.indexOf("---", 3);
-    if (closeIdx !== -1) {
-      const yaml = content.slice(3, closeIdx);
-      body = content.slice(closeIdx + 3).trim();
-      const extract = (key) => {
-        const m = yaml.match(new RegExp("^" + key + ":\\s*(.+)$", "m"));
-        if (!m) return undefined;
-        let v = m[1].trim();
-        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
-        return v || undefined;
-      };
-      name = extract("name") || name;
-      model = extract("model");
-      description = extract("description");
-    }
-  }
-  return { name, model, description, systemPrompt: body, report: name, title: description || name, isCustom: true };
-}
-
-// ── Agent defs 解析（每批元素统一解析） ─────────────────────────────
-
-// fallow-scan：内置工具型 def（无 .md，跑 fallow audit 静态分析）
-const FALLOW_DEF = { name: "fallow-scan", title: "FALLOW STATIC ANALYSIS", report: "fallow-scan", isFallow: true };
-
-function resolveAgentDefs(batchNames) {
-  return batchNames.map((item) => {
-    if (item === "fallow-scan") return FALLOW_DEF;
-    if (item.includes("/") || item.endsWith(".md")) return loadAgentMd(item);
-    return { name: item, report: item.replace(/^review-/, ""), title: item.toUpperCase() };
-  });
+  const b = state.batches[state.batches.length - 1];
+  const r = b && b.rounds && b.rounds[b.rounds.length - 1];
+  return (r && Array.isArray(r.modifiedFiles)) ? r.modifiedFiles : [];
 }
 
-// ── Build review calls ──────────────────────────────────────────────
-
-function buildReviewCall(def, round, max, batchIndex, roundDir) {
+function buildReviewCall(def, round, max, batchIndex, roundDir, scoped) {
   const header = "Batch " + batchIndex + " Round " + round + "/" + max + " — " + BATCH_NAMES[batchIndex - 1];
   const prevBatchesHint = batchIndex > 1
     ? "\nPrior batch reports (optional context): " + RUN_ROOT + "/batch-*/  (use read)"
@@ -316,6 +313,10 @@ function buildReviewCall(def, round, max, batchIndex, roundDir) {
     schema: reviewerSchema,
     description: def.name,
     timeoutMs: 1_800_000,
+    // returnMeta: true — 与 recursive-split 脚本的 executeActionAgent 对齐：失败时 resolve
+    // {value, error}，raw.error 可检测（review- 前缀兜底/结构化终止可达）；成功时
+    // value = parsedOutput ?? content，parseResult 作用于 raw.value（MF-1）。
+    returnMeta: true,
   };
 
   if (def.isFallow) {
@@ -329,7 +330,7 @@ function buildReviewCall(def, round, max, batchIndex, roundDir) {
         "Steps:",
         "1. Check if fallow is installed: `which fallow`",
         "2. If NOT installed: write the report with a one-line note, must_fix=0, suggestion=0.",
-        "3. If installed, run: `fallow audit --base " + target + " --format json --quiet`",
+        "3. If installed, run: `fallow audit --base " + lockedBase.base + " --format json --quiet`",
         "4. Extract: complexity hotspots, dead code, unused exports, circular deps",
         "5. Classify findings: critical/major count into must_fix; minor into suggestion.",
         "",
@@ -339,6 +340,50 @@ function buildReviewCall(def, round, max, batchIndex, roundDir) {
     };
   }
 
+  // R2+ 三段式分支（5.2）：round>1 且非 scoped → verify-first 对账 + known-remaining + 收敛 hunt。
+  // scoped 分支（recheck 限定）在下方单独处理（含对账段）。
+  if (round > 1 && !scoped) {
+    const prevRoundDir = RUN_ROOT + "/batch-" + batchIndex + "/round-" + (round - 1);
+    const r2Spec = def.isCustom
+      ? "\n\nReviewer specification (from agent file):\n" + def.systemPrompt
+      : "";
+    return {
+      ...base,
+      schema: { ...reviewerSchema, required: [...reviewerSchema.required, "reconciliation"] },
+      prompt: buildR2ReviewPrompt({
+        header, round, max, roundDir,
+        reportFile: def.report,
+        aggPath: prevRoundDir + "/aggregated.md",
+        fixResult: state.fixResults && state.fixResults.length
+          ? state.fixResults[state.fixResults.length - 1]
+          : null,
+        knownRemaining: (state.knownRemaining && Array.isArray(state.knownRemaining)) ? state.knownRemaining : [],
+      }) + r2Spec,
+      agent: def.isCustom ? undefined : def.name,
+    };
+  }
+
+  // recheck 限定分支（5.5）：clean agent 重派时只审 fix 改动文件 + 自检关联点
+  // （scope = modifiedFiles ∪ affected_files，后者来自 state.fixImpactFiles），不诱导全量重扫。
+  if (scoped) {
+    return {
+      ...base,
+      // m2: scoped 分支与 R2+ 分支一致——reconciliation 必填（recheck 也须对账前轮 fix）
+      schema: { ...reviewerSchema, required: [...reviewerSchema.required, "reconciliation"] },
+      prompt: buildScopedRecheckPrompt({
+        header, round, max, roundDir,
+        reportFile: def.report,
+        modifiedFiles: lastModifiedFiles(),
+        affectedFiles: (state.fixImpactFiles && Array.isArray(state.fixImpactFiles)) ? state.fixImpactFiles : [],
+        aggPath: RUN_ROOT + "/batch-" + batchIndex + "/round-" + (round - 1) + "/aggregated.md",
+        fixResult: state.fixResults && state.fixResults.length
+          ? state.fixResults[state.fixResults.length - 1]
+          : null,
+      }) + (def.isCustom ? "\n\nReviewer specification (from agent file):\n" + def.systemPrompt : ""),
+      agent: def.isCustom ? undefined : def.name,
+    };
+  }
+
   const spec = def.isCustom
     ? "\n\nReviewer specification (from agent file):\n" + def.systemPrompt
     : "";
@@ -359,11 +404,11 @@ function buildReviewCall(def, round, max, batchIndex, roundDir) {
   };
 }
 
-// agent 名解析失败（AgentRegistry not found）时，尝试 review- 前缀兜底
+// agent 名解析失败（AgentRegistry not found，报错文案 `Agent "${name}" not found.`）时，尝试 review- 前缀兜底
 async function runReviewAgent(call) {
   let raw = await agent(call);
-  if (raw && typeof raw === "object" && raw.error && typeof raw.error === "string"
-      && raw.error.includes("Agent not found") && call.agent && !call.agent.startsWith("review-")) {
+  if (raw && typeof raw === "object" && raw.error
+      && shouldRetryWithReviewPrefix(raw.error, call.agent)) {
     log("Agent not found: " + call.agent + " — retrying with review- prefix");
     raw = await agent({ ...call, agent: "review-" + call.agent });
   }
@@ -373,6 +418,9 @@ async function runReviewAgent(call) {
 // ── Main loop: batches (serial) × rounds (per-batch) ────────────────
 
 const state = loadState();
+// 5.6 锁定结果落 state.meta.baseHash（commit 1 声称与实现一致化，run 后可从 state.json 追溯审查基线）
+state.meta = state.meta || {};
+state.meta.baseHash = lockedBase.hash || "";
 let totalFixed = 0;
 let terminated = "clean";
 let finalMessage = "";
@@ -381,17 +429,24 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
   const defs = resolveAgentDefs(BATCHES[batchIndex - 1]);
   const cleanNames = new Set();
   let round = 0;
-  let prevTotal = -1;
+  let prevMustFix = -1;
   let stuckCount = 0;
   let batchClean = false;
   let roundHasFix = false; // recheckAfterFix 用：上轮是否有 fix
   const batchRounds = [];
 
+  // MF-1 批级 review 状态隔离：每批开始重置 issue 追踪 / 收敛计数 / known-remaining，
+  // 防止跨批 newFindings 语义污染（firstSeen 用批内 round 号写入、convergeStreak 跨批
+  // 累加会让前批收敛状态泄漏到后批，复合导致 converged 错误跳过后续批次）。
+  state.issues = undefined;
+  state.convergeStreak = 0;
+  state.knownRemaining = [];
+
   // 跨批跳过：agent 在更早批 clean 且此后无 fix → 本批不派发
   if (batchIndex > 1) {
     for (const def of defs) {
       const s = state.agentStatus[def.name];
-      if (s && s.lastCleanBatch && s.lastCleanBatch < batchIndex && s.lastCleanFixCount === state.fixCount) {
+      if (shouldSkipAgent(s, state.fixCount, batchIndex)) {
         cleanNames.add(def.name);
         log("Cross-batch skip: " + def.name + " (clean in batch " + s.lastCleanBatch + ", no fix since)");
       }
@@ -407,8 +462,10 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
     fs.mkdirSync(roundDir, { recursive: true });
 
     let active = defs.filter((def) => !(skipCleanAgents && cleanNames.has(def.name)));
+    let scopedClean = new Set(); // recheckAfterFix 重派时：上一轮 clean 的 agent 本轮走限定 prompt
     if (recheckAfterFix && round > 1 && roundHasFix) {
-      active = defs; // fix 后重派全批（回归防护）
+      scopedClean = new Set(cleanNames); // 重派前快照上一轮 clean 集合
+      active = defs; // fix 后重派全批（强回归模式）
       cleanNames.clear();
     }
 
@@ -419,21 +476,47 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
     }
 
     log("Review: " + active.map((d) => d.name).join(", ") + " (" + active.length + " agent(s) in parallel)...");
-    const calls = active.map((def) => buildReviewCall(def, round, maxRounds, batchIndex, roundDir));
-    const allRaw = await parallel(calls);
+    const calls = active.map((def) => buildReviewCall(def, round, maxRounds, batchIndex, roundDir, scopedClean.has(def.name)));
+    const allRaw = await parallel(calls.map(runReviewAgent));
 
     // per-agent 结果区分：parallel 结果与 calls 一一对应
     const reviewResults = [];
     const agentRoundResults = [];
+    const reconSeen = new Set(); // R2+ reconciliation 声明的上轮 ID（status !== fixed）——stuck ID 驱动数据源（5.1）
+    const reconEscalate = new Set(); // 5.1-5 escalate 声明：deferred 条目上下文改变 → 重新 open
+    const reconAll = new Set(); // M2: 所有 status 条目（含 fixed）的 prev_id 去重——reconcile 门控数据源
     for (let i = 0; i < allRaw.length; i++) {
       const raw = allRaw[i];
       if (raw && typeof raw === "object" && raw.error) {
-        // fail-fast：审查 agent 调用失败（含 AgentRegistry not found）不得静默跳过
-        fail("审查 agent 调用失败: " + active[i].name + " — " + raw.error);
+        // 审查 agent 调用失败（含 AgentRegistry not found / 超时）。不裸 throw——与
+        // aggregator-failure/stuck/fix-failure 路径一致：saveState + terminated 结构化终止，
+        // 保证 state.json 有记录、调用方拿到结构化结果而非裸异常（MF-3）。
+        state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+        saveState(state);
+        terminated = "review-failure";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": 审查 agent 调用失败 " + active[i].name + " — " + raw.error;
+        batchIndex = BATCHES.length + 1; // 终止外层循环
+        break;
       }
-      const parsed = parseResult(raw);
-      if (parsed && typeof parsed.must_fix === "number") {
+      const parsed = normalizeReviewResult(raw.value);
+      if (parsed) {
+        // 5.8 通用落盘：schema-only agent（report_content 无 report_file，如 doc-reviewer）→
+        // workflow 写盘到 <roundDir>/<def.report>.md 并填入 report_file（aggregator 读取路径不变）。
+        const reportPath = resolveReviewReportPath(parsed, roundDir, active[i].report);
+        if (reportPath && !(parsed.report_file && parsed.report_file.trim())) {
+          try {
+            fs.writeFileSync(reportPath, parsed.report_content || "", "utf-8");
+            parsed.report_file = reportPath;
+          } catch (e) {
+            log("WARN: failed to write report_content to " + reportPath + " — " + e.message);
+          }
+        }
         reviewResults.push(parsed);
+        for (const r of parsed.reconciliation) {
+          if (r.status === "escalate") reconEscalate.add(r.prev_id);
+          else if (r.status !== "fixed") reconSeen.add(r.prev_id);
+          reconAll.add(r.prev_id); // M2: 含 fixed——全 fixed 时 reconSeen 空但 reconcile 仍需执行
+        }
         const def = active[i];
         if (parsed.must_fix === 0) {
           recordAgentClean(state, def.name, batchIndex);
@@ -444,11 +527,18 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
         agentRoundResults.push({ name: def.name, must_fix: parsed.must_fix, suggestion: parsed.suggestion ?? 0, clean: parsed.must_fix === 0 });
       } else {
         // tools 受限的 agent（如 tools: read）会过滤掉 structured-output → schema 失效，
-        // 结果缺 must_fix。fail 信息完整 dump raw 便于定位。
-        fail("审查 agent 结果无效（缺 must_fix）: " + active[i].name + " raw=" + JSON.stringify(raw).slice(0, 400));
+        // 结果缺 must_fix。结构化终止（MF-3），raw 完整 dump 便于定位。
+        state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+        saveState(state);
+        terminated = "review-failure";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": 审查 agent 结果无效（缺 must_fix） " + active[i].name + " raw=" + JSON.stringify(raw.value).slice(0, 400);
+        batchIndex = BATCHES.length + 1; // 终止外层循环
+        break;
       }
     }
 
+    if (terminated === "review-failure") break; // 已结构化终止，退出 round 循环（MF-3）
+
     if (reviewResults.every((r) => r.must_fix === 0)) {
       log("Batch " + batchIndex + " round " + round + ": all agents clean.");
       batchRounds.push({ round, mustFix: 0, suggestion: reviewResults.reduce((a, r) => a + (r.suggestion ?? 0), 0), agents: agentRoundResults, modifiedFiles: [] });
@@ -459,63 +549,25 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
 
     // ── Aggregate（内置 prompt，不依赖任何 agent.md） ─────────
     const aggRaw = await agent({
-      prompt: [
-        "Batch " + batchIndex + "/" + BATCHES.length + " Round " + round + "/" + maxRounds + " — AGGREGATE REVIEWS",
-        "",
-        "You have TWO outputs: (1) a markdown report file and (2) a JSON return value.",
-        "",
-        "Sub-review results: " + JSON.stringify(reviewResults, null, 2),
-        "outputDir: " + roundDir,
-        "",
-        "─── PART 1: WRITE FILE ───────────────────────────────────",
-        "Write the human-readable aggregated report to:",
-        roundDir + "/aggregated.md",
-        "",
-        "Top section MUST be:",
-        "```",
-        "## Summary",
-        "- Must-fix: <N>",
-        "- Suggestions: <N>",
-        "- Infos: <N>",
-        "- Dimensions reviewed: <comma-separated>",
-        "- Dedup: <N> duplicates removed",
-        "```",
-        "",
-        "Followed by tables of Must-Fix Issues, Suggestions, Infos, and a Conclusion section.",
-        "The format `- Must-fix: N` and `- Suggestions: N` is critical: a fallback parser depends on it.",
-        "",
-        "─── PART 2: RETURN JSON (CRITICAL — loop reads THIS) ─────",
-        "Your FINAL response MUST be a single JSON object and NOTHING ELSE.",
-        "",
-        "Required shape (exact field names, no aliases, no extras):",
-        "{",
-        '  "report_file": "' + roundDir + '/aggregated.md",',
-        '  "must_fix": <integer>,',
-        '  "suggestion": <integer>',
-        "}",
-        "",
-        "STRICT RULES:",
-        "- Field names MUST be exactly: report_file, must_fix, suggestion",
-        "- must_fix and suggestion MUST be integers — NOT strings, NOT null, NOT undefined",
-        "- The JSON object MUST be the ONLY thing in your final response",
-        "- DO NOT wrap in markdown code fences, DO NOT add prose before/after",
-        "",
-        "─── SELF-CHECK before returning ──────────────────────────",
-        "1. Did you write " + roundDir + "/aggregated.md? If not, do it first.",
-        "2. Is must_fix in your JSON equal to the 'Must-fix: N' in your markdown?",
-        "3. Is your final response the bare JSON object, no fences, no prose?",
-      ].join("\n"),
+      prompt: buildAggregatorPrompt({
+        header: "Batch " + batchIndex + "/" + BATCHES.length + " Round " + round + "/" + maxRounds + " — AGGREGATE REVIEWS",
+        round, max: maxRounds, roundDir,
+        reviewResults,
+      }),
       model: MODEL,
       schema: aggregatorSchema,
       description: "aggregate",
       timeoutMs: 1_800_000,
+      returnMeta: true,
     });
 
-    let agg = normalizeAggregatorResult(aggRaw);
+    // returnMeta 下 aggRaw = {value, error}；失败时 value 为空串、error 在 finalMessage 透出（MF-1）
+    const aggValue = aggRaw?.value ?? aggRaw;
+    let agg = normalizeAggregatorResult(aggValue);
 
     if (!agg || typeof agg.must_fix !== "number") {
-      const rawPreview = (typeof aggRaw === "string" ? aggRaw : JSON.stringify(aggRaw)).slice(0, 200);
-      log("Aggregator JSON invalid (len=" + (aggRaw?.length ?? 0) + "): " + rawPreview);
+      const rawPreview = (aggValue === undefined ? "undefined" : typeof aggValue === "string" ? aggValue : JSON.stringify(aggValue)).slice(0, 200);
+      log("Aggregator JSON invalid (len=" + (typeof aggValue === "string" ? aggValue.length : 0) + "): " + rawPreview);
       const fallbackPath = (agg && agg.report_file) || (roundDir + "/aggregated.md");
       try {
         const content = fs.readFileSync(fallbackPath, "utf-8");
@@ -531,7 +583,8 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
         state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
         saveState(state);
         terminated = "aggregator-failure";
-        finalMessage = "Batch " + batchIndex + " round " + round + ": aggregator 失败且 fallback 解析失败";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": aggregator 失败且 fallback 解析失败"
+          + (aggRaw && typeof aggRaw === "object" && aggRaw.error ? " — " + aggRaw.error : "");
         batchIndex = BATCHES.length + 1; // 终止外层循环
         break;
       }
@@ -541,24 +594,159 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
     const suggestion = agg.suggestion ?? 0;
     log("Aggregated: " + mustFix + " must-fix + " + suggestion + " suggestion(s).");
 
+    // 5.1：R1 的 aggregator must_fix_ids 初始化 state.issues（数字 ID 起点）
+    if (round === 1 && agg.must_fix_ids && agg.must_fix_ids.length > 0) {
+      if (!state.issues) state.issues = {};
+      for (const entry of agg.must_fix_ids) {
+        const id = typeof entry === "string" ? entry : entry && entry.id;
+        if (!id || state.issues[id]) continue;
+        state.issues[id] = {
+          // severity 结构化（5.7）：aggregator 标注 critical/major/minor，converged 终止的
+          // 「无 critical」判定依赖它；旧格式（string）默认 major（must-fix 语义）。
+          firstSeen: 1,
+          severity: typeof entry === "string" ? "major" : (entry.severity || "major"),
+          status: "open",
+          history: [{ round: 1, status: "open" }], fixAttempts: 0,
+        };
+      }
+    }
+
     // ── Stuck detection ─────────────────────────────────────
-    const total = mustFix + suggestion;
-    if (prevTotal >= 0 && total >= prevTotal) {
-      stuckCount++;
-      if (stuckCount >= stuckThreshold) {
-        log("Stuck: total issues not decreasing for " + stuckThreshold + " rounds. Stopping.");
+    // 5.1 ID 驱动：R2+ 用 reconciliation 声明的 seenIds + reconcileIssues（同一 ID 连续 N 轮
+    // open/regressed）；无 reconciliation 数据（R1 或 reviewer 未填）降级计数式 updateStuckState
+    // （现状语义，MF-2 注释保留）。needs-redesign（fixAttempts>=2）在 wave 5 接入。
+    // M2: reconCount = 所有 status 条目的 prev_id 去重计数（含 fixed）——全 fixed（最常见
+    // 收敛路径）时 reconSeen 为空，但 reconciliation 有数据仍须调 reconcileIssues：
+    // fix-attempted → fixed 的唯一转换点（否则 fix-attempted 永不转 fixed）
+    const reconCount = reconAll.size;
+    // F1: 无对账数据（doc-reviewer-only 批 reconciliation 恒空）时，fix-attempted 条目
+    // 存在仍须执行 reconcile——空 seenIds 语义 = 未被重新报告 = 已修复（5.1「未出现→fixed」）
+    const hasFixAttempted = state.issues
+      ? Object.values(state.issues).some((i) => i.status === "fix-attempted")
+      : false;
+
+    // 5.1-2 R2+ 新发现 ID 契约（M2 移出 reconcile 分支，独立执行；F1 扩展为
+    // 「重新报告 = 未修复」转换）：aggregator 的 must_fix_ids 中
+    //   a) 不在 issues → 创建为新条目（firstSeen=round，severity 从 aggregator 标注）
+    //   b) 已存在且（fix-attempted 或 fixed）且本轮无对账数据（reconCount===0，
+    //      doc-reviewer 场景）→ 重新报告 = 修复失败：转 regressed + fixAttempts+1 + openStreak+1
+    //      （RC-7 needs-redesign 出口在无对账配置下可达；reconciliation 场景由
+    //      reconcileIssues 处理，避免双计）。fixed 重报分支（MF-2）：已确认修复的问题
+    //      再次被报告同样转 regressed——否则 fixed 停留 + 收敛终止组合会在默认配置下
+    //      R3 即以 converged 提前终止而 must-fix 仍活跃。
+    // newFindings 统计与 needs-redesign/fixAttempts 追踪对 R2+ 新发现生效。
+    if (round > 1 && state.issues && agg.must_fix_ids && agg.must_fix_ids.length > 0) {
+      let added = 0;
+      for (const entry of agg.must_fix_ids) {
+        const id = typeof entry === "string" ? entry : entry && entry.id;
+        if (!id) continue;
+        if (state.issues[id]) {
+          if (reconCount === 0 && (state.issues[id].status === "fix-attempted" || state.issues[id].status === "fixed")) {
+            state.issues[id].status = "regressed";
+            state.issues[id].fixAttempts = (state.issues[id].fixAttempts || 0) + 1;
+            state.issues[id].openStreak = (state.issues[id].openStreak || 0) + 1;
+            state.issues[id].severity = typeof entry === "string" ? "major" : (entry.severity || "major");
+            state.issues[id].history.push({ round, status: "regressed" });
+            added++;
+          }
+          continue;
+        }
+        state.issues[id] = {
+          firstSeen: round,
+          severity: typeof entry === "string" ? "major" : (entry.severity || "major"),
+          status: "open", openStreak: 1,
+          history: [{ round, status: "open" }], fixAttempts: 0,
+        };
+        added++;
+      }
+      if (added > 0) log("New findings tracked: " + added + " new or re-reported issue(s) in round " + round);
+    }
+
+    let stuck = { stuck: false };
+    if (round > 1 && (reconCount > 0 || hasFixAttempted)) {
+      const rec = reconcileIssues(state.issues || {}, { seenIds: reconSeen, escalateIds: reconEscalate, round, stuckThreshold });
+      state.issues = rec.issues;
+      state.knownRemaining = rec.knownRemaining;
+      stuck = { stuck: rec.stuck, stuckIds: rec.stuckIds };
+      log("Reconcile: " + Object.keys(rec.issues).length + " tracked issue(s), known-remaining: " + rec.knownRemaining.length);
+    } else {
+      const s = updateStuckState(prevMustFix, stuckCount, mustFix, stuckThreshold);
+      stuckCount = s.stuckCount;
+      prevMustFix = s.prevMustFix;
+      stuck = { stuck: s.stuck };
+    }
+    if (stuck.stuck) {
+      const stuckIds = (stuck.stuckIds || []).join(", ");
+      log("Stuck: issue(s) not converging for " + stuckThreshold + " rounds: " + stuckIds + ". Stopping.");
+      batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
+      state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+      saveState(state);
+      terminated = "stuck";
+      finalMessage = "Batch " + batchIndex + " round " + round + ": 问题 " + stuckIds + " 连续 " + stuckThreshold + " 轮未收敛。残留: "
+        + (state.knownRemaining && state.knownRemaining.length ? state.knownRemaining.join("; ") : "无 deferred");
+      batchIndex = BATCHES.length + 1;
+      break;
+    }
+
+    // 5.7 needs-redesign（RC-7）：fixAttempts >= maxFixAttempts 且 regressed → 终止。
+    // 顺序在 stuck 之后：stuck（一直在）信息更宏观，needs-redesign（修不好）更具体，先 stuck 后 redesign。
+    if (round > 1 && state.issues) {
+      const redesign = findNeedsRedesign(state.issues, maxFixAttempts);
+      if (redesign.length > 0) {
+        const ids = redesign.map((r) => r.issue_id).join(", ");
+        // 5.7 message 三要素：ID + 修复历史摘要 + 残留清单（history 全文随 state.json 落盘）
+        const historySummary = redesign.map((r) => {
+          const hist = (r.history || []).map((h) => "R" + h.round + ":" + h.status).join(" -> ");
+          return r.issue_id + " [" + (hist || "no history") + "]";
+        }).join("; ");
+        log("Needs redesign: " + ids + " not converging after " + maxFixAttempts + " fix attempts. Stopping.");
         batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
         state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
         saveState(state);
-        terminated = "stuck";
-        finalMessage = "Batch " + batchIndex + " round " + round + ": 总问题数连续 " + stuckThreshold + " 轮不下降";
+        terminated = "needs-redesign";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": 问题 " + historySummary + " 经 " + maxFixAttempts
+          + " 次修复仍未收敛，属于需要重新设计而非继续补丁的结构性问题，请人工介入。残留: "
+          + (state.knownRemaining && state.knownRemaining.length ? state.knownRemaining.join("; ") : "无 deferred");
         batchIndex = BATCHES.length + 1;
         break;
       }
-    } else {
-      stuckCount = 0;
+
+      // 5.7 新发现率收敛：连续 convergeRounds 轮新发现 <= convergeNewIssues → converged
+      const newIssues = Object.values(state.issues).filter((i) => i.firstSeen === round);
+      const newFindings = newIssues.length;
+      const newFindingsCritical = newIssues.filter((i) => i.severity === "critical").length;
+      const conv = checkConvergence({
+        prevStreak: state.convergeStreak || 0, newFindings, newFindingsCritical,
+        convergeNewIssues, convergeRounds,
+      });
+      state.convergeStreak = conv.streak;
+      // MF-2/S-21 收敛门槛：新发现率收敛 ≠ 问题已解决——必须同时满足「无 open/regressed
+      // 活跃条目」才允许 converged 终止。fixed 条目复发（reconcile/merge 已转 regressed）
+      // 后活跃条目存在 → 不收敛，继续修复循环（默认配置下 R3 复发不再提前终止）。
+      // issues 无追踪（aggregator 缺 must_fix_ids）时回退 mustFix===0 数字级判定，
+      // 避免 must_fix>0 照常收敛掩盖未处理问题（S-21）。
+      const trackedCount = Object.keys(state.issues || {}).length;
+      const activeIssues = Object.values(state.issues || {})
+        .filter((i) => i.status === "open" || i.status === "regressed");
+      const noActiveIssues = trackedCount === 0 ? mustFix === 0 : activeIssues.length === 0;
+      if (conv.converged && noActiveIssues) {
+        // MF-2 ④：converged 消息列出 open issue ID（对齐 max-rounds 的 remainingIds 逻辑）。
+        // 门槛保证正常路径此处为空；状态漂移时调用方仍能看到残留而非「无 deferred」误报。
+        const remainingIds = Object.entries(state.issues || {})
+          .filter(([, i]) => i.status !== "fixed" && i.status !== "deferred")
+          .map(([id]) => id);
+        log("Converged: new findings <= " + convergeNewIssues + " for " + convergeRounds + " rounds. Batch " + batchIndex + " done, proceeding to next batch.");
+        batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
+        saveState(state);
+        terminated = "converged";
+        finalMessage = "Batch " + batchIndex + " round " + round + ": 新发现率收敛（连续 " + convergeRounds
+          + " 轮新问题 ≤" + convergeNewIssues + "）。残留: "
+          + (remainingIds.length ? remainingIds.join(", ") : "无")
+          + (state.knownRemaining && state.knownRemaining.length ? "；deferred: " + state.knownRemaining.join("; ") : "");
+        batchClean = true; // MF-1: 与 clean 一致，让外层 for 推进下一批（不跳过后续批次）
+        break;
+      }
     }
-    prevTotal = total;
 
     // ── Fix ─────────────────────────────────────────────────
     phase("Fix");
@@ -585,35 +773,44 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       : "- Do NOT commit. Leave the fixes in the working tree (autoCommit=false).";
 
     const fxRaw = await agent({
-      prompt: [
-        "Fix round " + round + " (batch " + batchIndex + "): Fix ALL must-fix issues from the aggregated review report below.",
-        "",
-        "## Aggregated Review Report",
+      prompt: buildFixPrompt({
+        header: "Fix round " + round + " (batch " + batchIndex + ")",
         reportContent,
-        "",
-        "## Instructions",
-        "- Fix every must-fix issue listed in the report",
-        "- Apply the MINIMAL correct fix (no refactoring, no style changes)",
-        "- Verify each fix by reading the changed file afterwards",
-        fixPrompt,
+        fixPrompt: FIX_DEF && FIX_DEF.isCustom
+          ? fixPrompt + "\n\nFixer specification (from agent file):\n" + FIX_DEF.systemPrompt
+          : fixPrompt,
         commitInstr,
-        "",
-        "Return the count of issues fixed.",
-      ].join("\n"),
-      schema: {
-        type: "object",
-        properties: {
-          fixed_count: { type: "number", description: "Number of issues fixed" },
-          fixes: { type: "array", items: { type: "string" }, description: "One-line description of each fix" },
-        },
-        required: ["fixed_count"],
-      },
-      model: MODEL,
-      description: "fix",
+        caution: agg.fixes_caution && agg.fixes_caution.length ? agg.fixes_caution : [],
+      }),
+      schema: fixSchema,
+      // 与 buildReviewCall 的 model: MODEL || def.model 对齐：custom fixer.md 的
+      // frontmatter model 字段同样生效（之前丢弃了 FIX_DEF.model，只在 review 阶段消费）
+      model: MODEL || (FIX_DEF && FIX_DEF.model),
+      description: (FIX_DEF && FIX_DEF.name) || "fix",
+      // info #15: 显式 timeoutMs 与 review/aggregator 档位一致（fix 是写操作中最长阶段，
+      // 不依赖引擎默认值——引擎默认值变化不会悄然缩短 fix 预算）
+      timeoutMs: 1_800_000,
+      returnMeta: true,
+      ...(FIX_DEF && !FIX_DEF.isCustom ? { agent: FIX_DEF.name } : {}),
     });
 
-    const fx = parseResult(fxRaw);
-    if (!fx) {
+    // returnMeta 下 fxRaw = {value, error}：先查 error（失败分支可达，MF-1），再对 value 做 parseResult
+    if (fxRaw && typeof fxRaw === "object" && fxRaw.error) {
+      // fix agent 调用失败（AgentRegistry not found / 超时等）。
+      // 与 review 路径（raw.error → review-failure）对齐：结构化终止而非静默当成功——
+      // 否则 fixed_count 缺失被 `?? mustFix` 回退，totalFixed 虚增且 must_fix 不降白跑轮次（MF-1）。
+      log("Fix agent failed, stopping.");
+      batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
+      state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+      saveState(state);
+      terminated = "fix-failure";
+      finalMessage = "Batch " + batchIndex + " round " + round + ": fix agent 调用失败 — " + fxRaw.error;
+      batchIndex = BATCHES.length + 1;
+      break;
+    }
+    const fx = parseResult(fxRaw.value);
+    const fixResult = fx ? normalizeFixResult(fx) : null;
+    if (!fixResult) {
       log("Fix agent failed, stopping.");
       batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
       state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
@@ -624,7 +821,83 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       break;
     }
 
-    const fixedCount = fx.fixed_count ?? mustFix;
+    // ES3 硬校验（5.3 红线，恢复 mustFixIds 交叉校验——wave 3 后 agg.must_fix_ids
+    // 已是标准字段）：(1) deferred 只允许 minor；(2) must-fix 必须全进 fixes[]（漏修
+    // 判 violation）。任一违规 → fix-failure（结构化终止）
+    const es3Violations = validateFixResult(fixResult, agg.must_fix_ids);
+    if (es3Violations.length > 0) {
+      // m7: violation 分两类——deferred 非 minor / must-fix 漏修（must-fix-not-fixed），
+      // finalMessage 文案区分：统一文案会把漏修误报成 defer 违规，误导修复方向
+      const parts = es3Violations.map((v) =>
+        v.severity === "must-fix-not-fixed"
+          ? "must-fix 未在 fixes[] 中修复（漏修）— " + v.issue_id
+          : "deferred 含非 minor 条目（must-fix 不得 defer）— " + v.issue_id + "(" + v.severity + ")"
+      );
+      log("ES3 violation: " + JSON.stringify(es3Violations));
+      batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles: [] });
+      state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
+      saveState(state);
+      terminated = "fix-failure";
+      finalMessage = "Batch " + batchIndex + " round " + round + ": " + parts.join("; ");
+      batchIndex = BATCHES.length + 1;
+      break;
+    }
+
+    // ES2 软校验（5.3 证据标准）：defer 理由过短/无实质 → warning 日志（不终止）
+    for (const d of fixResult.deferred) {
+      const reason = typeof d.reason === "string" ? d.reason : "";
+      if (reason.trim().length < 20) {
+        log("WARN: deferred reason too short / no concrete cost description: " + JSON.stringify(d));
+      }
+    }
+
+    // affected_files 并入 state.fixImpactFiles（5.3/5.5）：recheck scope = modifiedFiles ∪ fixImpactFiles
+    const impactFiles = [];
+    for (const f of fixResult.fixes) {
+      if (Array.isArray(f.affected_files)) {
+        for (const af of f.affected_files) {
+          if (typeof af === "string" && af.trim() && !impactFiles.includes(af.trim())) impactFiles.push(af.trim());
+        }
+      }
+    }
+    state.fixImpactFiles = impactFiles;
+
+    // m4: 先初始化容器——aggregator JSON 无效走 parseAggregatedMd 回退时 agg 无
+    // must_fix_ids → R1 初始化跳过 → state.issues undefined；此处初始化保证 deferred
+    // 写入与 knownRemaining 同步链路生效（否则 knownRemaining 恒空，deferred 跨轮继承整链失效）
+    if (!state.issues) state.issues = {};
+    // 5.1：fix 结果标记 fix-attempted（ID 对账驱动）+ fixResults 落库（R2+ prompt 输入）
+    for (const f of fixResult.fixes) {
+      if (f && typeof f.issue_id === "string" && state.issues[f.issue_id]) {
+        state.issues[f.issue_id].status = "fix-attempted";
+        state.issues[f.issue_id].history.push({ round, status: "fix-attempted" });
+      }
+    }
+    // 5.3-4 deferred 写入 state.issues（known-remaining 跨轮继承链路）：deferred 条目
+    // 以 status=deferred 入 issues，据此生成 knownRemaining 传给 R2+ prompt。
+    // 若 ID 已存在（曾被修复/降级）→ 更新状态 + reason；不存在（S-x minor）→ 新建。
+    for (const d of fixResult.deferred) {
+      if (!d || typeof d.issue_id !== "string" || !d.issue_id) continue;
+      const reason = typeof d.reason === "string" ? d.reason : "";
+      if (state.issues[d.issue_id]) {
+        state.issues[d.issue_id].status = "deferred";
+        state.issues[d.issue_id].deferredReason = reason;
+        state.issues[d.issue_id].history.push({ round, status: "deferred" });
+      } else {
+        state.issues[d.issue_id] = {
+          firstSeen: round, severity: "minor", status: "deferred",
+          deferredReason: reason,
+          history: [{ round, status: "deferred" }], fixAttempts: 0,
+        };
+      }
+    }
+    // known-remaining 同步更新：deferred 在本轮 fix 后即生效，R2+ prompt 立即消费
+    // （不依赖下轮 reconcile 才生成——否则滞后一轮，reviewer 本轮看不到 deferred 清单）
+    state.knownRemaining = computeKnownRemaining(state.issues);
+    if (!state.fixResults) state.fixResults = [];
+    state.fixResults.push(fixResult);
+
+    const fixedCount = fixResult.fixed_count ?? mustFix;
     totalFixed += fixedCount;
     state.fixCount++;
     roundHasFix = true;
@@ -639,6 +912,9 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
       } catch { /* empty */ }
     }
     batchRounds.push({ round, mustFix, suggestion, agents: agentRoundResults, modifiedFiles });
+    // M4: 批内即时字段——下轮 scoped 分支（recheckAfterFix=true）从
+    // state.lastModifiedFiles 读本批 fix 的真实改动文件（git 实测兜底）
+    state.lastModifiedFiles = modifiedFiles;
     saveState(state);
 
     log("Fixed " + fixedCount + " issue(s). Total: " + totalFixed + ". Modified " + modifiedFiles.length + " file(s). Continuing...");
@@ -648,10 +924,19 @@ for (let batchIndex = 1; batchIndex <= BATCHES.length; batchIndex++) {
 
   state.batches.push({ index: batchIndex, name: BATCH_NAMES[batchIndex - 1], rounds: batchRounds });
 
-  if (!batchClean) {
-    // 该批达到 maxRounds 仍残留 must-fix → fail-fast，不进入后续批
-    terminated = "max-rounds";
-    finalMessage = "Batch " + batchIndex + " (" + BATCH_NAMES[batchIndex - 1] + ") 达到 maxRounds=" + maxRounds + " 仍有 must-fix，终止整个 workflow";
+  terminated = resolveBatchTerminated(batchClean, terminated);
+  if (terminated === "max-rounds") {
+    // 该批达到 maxRounds 仍残留 must-fix → fail-fast，不进入后续批。
+    // 5.9 残留清单：未 fixed 的 issues（status != fixed/deferred）+ known-remaining。
+    const remainingIds = state.issues
+      ? Object.entries(state.issues)
+          .filter(([, i]) => i.status !== "fixed" && i.status !== "deferred")
+          .map(([id]) => id)
+      : [];
+    finalMessage = "Batch " + batchIndex + " (" + BATCH_NAMES[batchIndex - 1] + ") 达到 maxRounds=" + maxRounds
+      + " 仍有 must-fix，终止整个 workflow。残留: "
+      + (remainingIds.length ? remainingIds.join(", ") : "(issues 未追踪)")
+      + (state.knownRemaining && state.knownRemaining.length ? "；deferred: " + state.knownRemaining.join("; ") : "");
     log(finalMessage);
     saveState(state);
     batchIndex = BATCHES.length + 1;
@@ -671,7 +956,15 @@ return {
   targetType,
   target,
   runDir: RUN_ROOT,
+  // 5.9 terminated 透出：非 clean 时 message 含终止原因 + 残留 ID 清单 + deferred 理由
+  // （stuck/needs-redesign/converged/max-rounds/*-failure 均由 finalMessage 承载）。
+  // 渲染层特判（launcher 对 terminated 非 clean 的视觉区分）留 TODO：当前 tool 结果
+  // 已含完整 message，主 agent 可直接感知差异。
+  // 5.9 视觉区分：非 clean 终止加 [UNRESOLVED] 前缀（tool 结果即主 agent 可见层，
+  // launcher 透传 message——无需跨模块渲染特判，W5C3 决策更新）
   message: terminated === "clean"
     ? "All batches clean. " + totalFixed + " issue(s) fixed total. State: " + STATE_FILE
-    : finalMessage + ". State: " + STATE_FILE,
+    : terminated === "converged"
+      ? finalMessage + " " + totalFixed + " issue(s) fixed total. State: " + STATE_FILE
+      : "[UNRESOLVED] " + finalMessage + ". State: " + STATE_FILE,
 };