@ifrankwang/openspec-agents 0.135.0 → 0.137.0

package/.mcp-server/cli.mjs

@@ -4056,13 +4056,14 @@ var require_fast_uri = __commonJS(function(exports, module) {
       if (!malformedIPLiteral) {
         malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP);
       }
-      if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
-        if (uri.indexOf("%") !== -1) {
-          if (parsed.host !== undefined && !malformedIPLiteral) {
-            const host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
-            parsed.host = reescapeHostDelimiters(host, isIP);
-          }
+      if (uri.indexOf("%") !== -1 && parsed.host !== undefined && !malformedIPLiteral) {
+        let host = isIP ? parsed.host : normalizePercentEncoding(parsed.host, true);
+        if (!isIP) {
+          host = normalizePercentEncoding(host.toLowerCase());
         }
+        parsed.host = reescapeHostDelimiters(host, isIP);
+      }
+      if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
         if (parsed.path) {
           parsed.path = normalizePathEncoding(parsed.path);
         }
@@ -21662,6 +21663,14 @@ async function getCurrentBranch(worktree) {
 async function getMergeBase(worktree, baseBranch) {
   return runGit(worktree, ["merge-base", "HEAD", baseBranch]);
 }
+async function isAncestor(worktree, a, b) {
+  const r = await runGitChecked(worktree, ["merge-base", "--is-ancestor", a, b]);
+  if (r.success)
+    return true;
+  if (r.exitCode === 1)
+    return false;
+  throw new Error(`无法判断 "${a}" 是否为 "${b}" 的祖先：${r.stderr}`);
+}
 async function isLocalBranch(worktree, branch) {
   const r = await runGitChecked(worktree, ["rev-parse", "--verify", `refs/heads/${branch}`]);
   return r.success;
@@ -21798,7 +21807,7 @@ async function mergeBranchToTarget(repoDir, sourceBranch, targetBranch) {
           success: false,
           conflict: false,
           blockedMessage: [
-            `- **原因**: 目标分支 \`${targetBranch}\` 正被主仓库检出，且以下本地改动文件与任务组合并将写入的文件重合；为避免覆盖本地改动，本次未执行任何合并动作（分支引用未动、无半成品）：`,
+            `- **原因**: 目标分支 \`${targetBranch}\` 正被主仓库检出，且以下本地改动文件与变更分支合并将写入的文件重合；为避免覆盖本地改动，本次未执行任何合并动作（分支引用未动、无半成品）：`,
             ...overlap.map((f) => `  - \`${f}\``),
             `- **处理**: 请先 commit/stash/移除上述文件的本地改动后重试；或自行执行 \`git merge ${sourceBranch}\`（真实合并自带脏工作区保护）。`
           ].join(`
@@ -21882,6 +21891,7 @@ async function mergeBranchToTarget(repoDir, sourceBranch, targetBranch) {
   }
   return { success: true, conflict: false };
 }
+var RESTORABLE_WORKTREE_BRANCH_PREFIXES = ["change/", "review/", "task-group/"];
 async function discoverDiskWorktrees(worktree) {
   const result = [];
   const wtList = await runGit(worktree, ["worktree", "list"]);
@@ -21890,7 +21900,7 @@ async function discoverDiskWorktrees(worktree) {
     const m = line.match(/^(\S+)\s+[0-9a-f]+\s+\[(.+?)\]/);
     if (m) {
       const branch = m[2].trim();
-      if (branch.startsWith("task-group/") || branch.startsWith("review/")) {
+      if (RESTORABLE_WORKTREE_BRANCH_PREFIXES.some((p) => branch.startsWith(p))) {
         result.push({ branch, path: m[1].trim() });
       }
     }
@@ -22194,6 +22204,9 @@ function isTaskGroupSettled(item) {
   const childrenSettled = item.children.filter((c) => c.type === "task").every((c) => c.phase === "todo" || isTerminalPhase(c.phase));
   return noTags && childrenSettled;
 }
+function isFinalTaskGroup(state, item) {
+  return state.workItems.filter((w) => w.id.startsWith("task:") && w.id !== item.id).every(isTaskGroupSettled);
+}
 function isBlockingSeverity(severity) {
   return severity !== undefined && BLOCKING_SEVERITIES.includes(severity);
 }
@@ -27031,7 +27044,7 @@ function renderWorktreeSection(state, tg, opts) {
         lines.push("- **审查范围**: 全量代码库审查（无区间界定，工具检查与审查覆盖整个代码库）");
       }
     } else if (tg.baseRef) {
-      lines.push(`- **变更范围**: 用 \`git -C ${tg.worktreePath} diff --name-only ${tg.baseRef}..HEAD\` 查询本 change 全部已提交变更文件`);
+      lines.push(`- **变更范围**: 用 \`git -C ${tg.worktreePath} diff --name-only ${tg.baseRef}..HEAD\` 查询本任务组的已提交变更文件`);
     }
     lines.push("- **⚠️ 约束**: 所有读写和 git 操作均在此目录下进行；严禁直接修改主仓库/主分支路径下的文件（如 `<repo>/openspec/...`）");
     lines.push("- **路径解析**: 推荐阅读文档均为相对 worktree 路径的引用，一律以 worktree 路径为基准解析，禁止从主仓库根目录解析");
@@ -27347,13 +27360,14 @@ function renderTerminalPhase(item, state, caller) {
     return lines.join(`
 `);
   }
+  const finalGroup = state ? isFinalTaskGroup(state, item) : true;
   if (item.metadata["completed_at"] !== undefined) {
     return [
       "# ✅ 任务组已完成",
       "",
       `- **完成时间**: ${item.metadata["completed_at"]}`,
       "",
-      "编排已完成并收尾。",
+      finalGroup ? "本任务组为最后一个收口任务组，change 收口已完成：变更分支已合并回基准分支，编排已完成并收尾。" : "本任务组已完成，变更保留在 change 分支上，待全部任务组完成后统一收口合并。",
       "",
       ...renderDeploymentNotesSection(state, caller)
     ].join(`
@@ -27362,7 +27376,8 @@ function renderTerminalPhase(item, state, caller) {
   return [
     "# \uD83C\uDFC1 任务组已完成，待收尾",
     "",
-    "全部审核层已通过。调用 `opx_orch_complete_task_group` 合并分支并完成收尾。",
+    "全部审核层已通过。",
+    finalGroup ? "调用 `opx_orch_complete_task_group` 完成 change 收口（把变更分支合并回基准分支并清理）。" : "调用 `opx_orch_complete_task_group` 完成任务组收尾（变更保留在 change 分支，统一收口时合并）。",
     "",
     ...renderDeploymentNotesSection(state, caller)
   ].join(`
@@ -27379,7 +27394,7 @@ function renderDeploymentNotesSection(state, caller) {
     "",
     "向用户汇报本次变更的部署注意事项：",
     "",
-    `- 阅读主仓库 \`openspec/changes/${state.changeId}/\` 下规划文档（design.md、tasks.md、proposal.md、specs/）提取部署要点：数据/结构变更脚本执行、消息队列/缓存等中间件配置调整、新增配置项或功能开关、外部接口契约变化`,
+    `- 阅读主仓库 \`openspec/changes/${state.changeId}/\` 下规划文档（design.md、tasks.md、proposal.md、specs/）提取部署要点：数据/结构变更脚本执行、消息队列/缓存等中间件配置调整、新增配置项或功能开关、外部接口契约变化、依赖清单/构建配置变更（合并后需在主仓库重装依赖、重新构建）`,
     "- 无规划文档时跳过文档提取，仅转述下方实施补充点",
     ""
   ];
@@ -27763,7 +27778,7 @@ function renderAgentWorking(item, rec, step, common, ctxAgent, state, tg, toolCh
   lines.push(...eff.lines);
   n = eff.nextNum;
   if (tg.worktreePath && tg.baseRef) {
-    lines.push(`${n++}. 用上方「变更范围」命令获取本 change 全部已提交变更文件清单，作为本次实施/修改范围；审查/报告范围以当前 step 指令为准`);
+    lines.push(`${n++}. 用上方「变更范围」命令获取本任务组的已提交变更文件清单，作为本次实施/修改范围；审查/报告范围以当前 step 指令为准`);
   }
   lines.push(`${n++}. 执行当前 step（\`${rec.stepId}\`）职责范围内的全部工作——遵循所有已加载 skill 的全部规范与约束`);
   lines.push(`${n++}. 逐项检视所有已加载 skill 的 MUST 规范，确认全部满足（不满足则补做，不得跳过）`);
@@ -27976,7 +27991,7 @@ function renderToolChangesEvidence(item, tg, toolChanges, kind) {
 `)];
   }
   if (checkpoint) {
-    lines.push(`- **口径**: 本次为「${label.title}（${checkpoint}..HEAD）」的增量区间（含已提交与未提交的非 openspec 变更）；` + `与上方「变更范围」（${baseRef ?? "(无)"}..HEAD 整个 change 累计口径）不同`, "");
+    lines.push(`- **口径**: 本次为「${label.title}（${checkpoint}..HEAD）」的增量区间（含已提交与未提交的非 openspec 变更）；` + `与上方「变更范围」（${baseRef ?? "(无)"}..HEAD 本任务组累计口径）不同`, "");
   } else if (baseRef) {
     lines.push(`- **口径**: 本次区间以基线（${baseRef}..HEAD）兜底，与上方「变更范围」一致（首次进入，无${label.lastCheck}记录；` + "含已提交与未提交的非 openspec 变更）", "");
   } else {
@@ -28312,7 +28327,16 @@ function applyRecoveryState(item, recovery, parsedTasks, state) {
     if ((recovery?.reset_steps ?? []).includes("quality_review")) {
       clearStepTags(item, "quality_review");
     }
-    item.currentStep = "quality_review";
+    const workflow = loadWorkflowFile(resolveWorkflowPath(state));
+    item.currentStep = firstUnpassedReviewStep(item, workflow);
+    if (item.currentStep === null) {
+      const unfinishedTasks = item.children.filter((child) => child.type === "task" && !isTerminalPhase(child.phase));
+      if (unfinishedTasks.length === 0) {
+        item.phase = "done";
+      } else {
+        item.currentStep = "quality_review";
+      }
+    }
     syncTaskChildren(item, parsedTasks, { defaultStatus: "done" });
     return;
   }
@@ -28797,17 +28821,75 @@ async function bindReviewWorktreeRefs(item, worktreePath, branch, state) {
   }
   delete item.metadata["base_ref"];
 }
-async function bindWorktreeRefs(item, worktreePath, branch, baseBranch, opts = {}) {
+async function bindWorktreeRefs(item, worktreePath, branch) {
   item.metadata["worktree_path"] = worktreePath;
   item.metadata["branch_name"] = branch;
-  const baseRef = await getMergeBase(worktreePath, baseBranch);
-  if (!baseRef) {
-    if (opts.requireBaseRef) {
-      throw new Error(`worktree 创建成功但无法获取与 ${baseBranch} 的 merge-base：${worktreePath}`);
-    }
-    return;
+  const existing = item.metadata["scope_start_oid"];
+  if (typeof existing !== "string" || !await isAncestor(worktreePath, existing, branch)) {
+    const head = (await runGit(worktreePath, ["rev-parse", branch])).trim();
+    if (!head)
+      throw new Error(`worktree 绑定成功但无法获取 ${branch} 的 HEAD：${worktreePath}`);
+    item.metadata["scope_start_oid"] = head;
+  }
+  item.metadata["base_ref"] = item.metadata["scope_start_oid"];
+}
+function deriveChangeBranch(changeId) {
+  return `change/${normalizeSessionToken(changeId)}`;
+}
+async function ensureChangeBranch(repoRoot, branch, baseBranch) {
+  if (await isLocalBranch(repoRoot, branch))
+    return false;
+  const created = await runGitChecked(repoRoot, ["branch", branch, baseBranch]);
+  if (!created.success)
+    throw new Error(`创建分支 "${branch}"（fork 自 ${baseBranch}）失败：${created.stderr}`);
+  return true;
+}
+async function ensureChangeWorktree(repoRoot, state, item, branch, defaultPath) {
+  await ensureChangeBranch(repoRoot, branch, state.baseBranch);
+  const wtList = await runGit(repoRoot, ["worktree", "list"]);
+  const existingLine = wtList.split(`
+`).find((l) => {
+    const m = l.match(/^(\S+)\s+[0-9a-f]+\s+\[(.+?)\]/);
+    return m && m[2].trim() === branch;
+  });
+  const registeredPath = existingLine ? existingLine.match(/^(\S+)/)?.[1] : undefined;
+  const targetPath = registeredPath ?? defaultPath;
+  if (!await pathExists(targetPath)) {
+    await runGitChecked(repoRoot, ["worktree", "prune"]);
+    await runGit(repoRoot, ["worktree", "add", targetPath, branch]);
+    await bindWorktreeRefs(item, targetPath, branch);
+    return { path: targetPath, reused: false };
+  }
+  if (!registeredPath) {
+    const addRes = await runGitChecked(repoRoot, ["worktree", "add", targetPath, branch]);
+    if (!addRes.success) {
+      throw new Error(`无法在 "${targetPath}" 就位 worktree：目录已存在且不是检出分支 "${branch}" 的 git worktree（git: ${addRes.stderr}）。
+` + `请人工确认该目录内容并处理（删除或迁移）后重试。`);
+    }
+    await bindWorktreeRefs(item, targetPath, branch);
+    return { path: targetPath, reused: false };
+  }
+  const statusOut = await runGit(targetPath, ["status", "--porcelain"]);
+  const dirtyPaths = statusOut.split(`
+`).map((l) => l.trim()).filter(Boolean).map((l) => {
+    const f = l.replace(/^\S+\s+/, "");
+    return (f.includes(" -> ") ? f.split(" -> ").pop() : f).replace(/^"+|"+$/g, "");
+  }).filter(Boolean);
+  const codeDirty = dirtyPaths.filter((p) => !p.startsWith("openspec/"));
+  if (codeDirty.length > 0) {
+    throw new Error(`已有 worktree "${targetPath}" 存在未提交的代码文件变更（${codeDirty.join("、")}），无法自动处理。
+` + `请先在该 worktree 内 commit 或 stash 后重试。`);
+  }
+  if (dirtyPaths.length > 0) {
+    const addResult = await runGitChecked(targetPath, ["add", "--", ...dirtyPaths]);
+    if (!addResult.success)
+      throw new Error(`worktree openspec 目录 git add 失败：${addResult.stderr}`);
+    const commitResult = await runGitChecked(targetPath, ["commit", "-m", "docs(openspec): auto-commit before worktree reuse"]);
+    if (!commitResult.success)
+      throw new Error(`worktree openspec 目录 git commit 失败：${commitResult.stderr}`);
   }
-  item.metadata["base_ref"] = baseRef;
+  await bindWorktreeRefs(item, targetPath, branch);
+  return { path: targetPath, reused: true };
 }
 async function setWorktreeExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_set_worktree");
@@ -28818,6 +28900,7 @@ async function setWorktreeExecute(params, ctx) {
   if (!item)
     throw new Error(`工作项 "task:${state.taskGroupId}" 缺失，请重新调用 opx_orch_init。`);
   const repoRoot = ctx.worktree;
+  const isReview = state.kind === "review";
   const rawBranch = params.branch_name ?? "";
   if (rawBranch !== "") {
     const check = await runGitChecked(repoRoot, ["check-ref-format", "--branch", rawBranch]);
@@ -28825,13 +28908,18 @@ async function setWorktreeExecute(params, ctx) {
       throw new Error(`分支名 "${rawBranch}" 不合法，请修正后重试。`);
     }
   }
-  const isReview = state.kind === "review";
-  const branch = rawBranch || (isReview ? `review/${state.changeId}` : `task-group/${state.changeId}/${state.taskGroupId}`);
+  const branch = rawBranch || (isReview ? `review/${state.changeId}` : deriveChangeBranch(state.changeId));
+  if (!isReview) {
+    const check = await runGitChecked(repoRoot, ["check-ref-format", "--branch", branch]);
+    if (!check.success) {
+      throw new Error(`派生分支名 "${branch}" 不合法（change_id="${state.changeId}"），请修正 change_id 或显式传入 branch_name。`);
+    }
+  }
   let wtPath;
   if (params.worktree_path) {
     wtPath = assertPathWithin(repoRoot, params.worktree_path, "worktree_path");
   } else {
-    wtPath = isReview ? path6.join(repoRoot, ".worktree", state.changeId, "review") : path6.join(repoRoot, ".worktree", state.changeId, `task-group-${state.taskGroupId}`);
+    wtPath = isReview ? path6.join(repoRoot, ".worktree", state.changeId, "review") : path6.join(repoRoot, ".worktree", state.changeId, "ws");
   }
   const changeStatus = await runGit(repoRoot, ["status", "--porcelain", `openspec/changes/${state.changeId}/`]);
   if (changeStatus.trim().length > 0) {
@@ -28842,61 +28930,57 @@ async function setWorktreeExecute(params, ctx) {
     if (!commitResult.success)
       throw new Error(`change 目录 git commit 失败：${commitResult.stderr}`);
   }
-  const wtList = await runGit(repoRoot, ["worktree", "list"]);
-  const existingLine = wtList.split(`
-`).find((l) => {
-    const m = l.match(/^(\S+)\s+[0-9a-f]+\s+\[(.+?)\]/);
-    return m && m[2].trim() === branch;
-  });
-  const existingPath = existingLine ? existingLine.match(/^(\S+)/)?.[1] : undefined;
   let reused = false;
-  if (existingPath) {
-    const baseHead = await runGit(repoRoot, ["rev-parse", state.baseBranch]);
-    const mergeResult = await runGitChecked(existingPath, ["merge", "--ff-only", baseHead]);
-    if (mergeResult.success) {
-      if (isReview)
+  if (isReview) {
+    const wtList = await runGit(repoRoot, ["worktree", "list"]);
+    const existingLine = wtList.split(`
+`).find((l) => {
+      const m = l.match(/^(\S+)\s+[0-9a-f]+\s+\[(.+?)\]/);
+      return m && m[2].trim() === branch;
+    });
+    const existingPath = existingLine ? existingLine.match(/^(\S+)/)?.[1] : undefined;
+    if (existingPath) {
+      const baseHead = await runGit(repoRoot, ["rev-parse", state.baseBranch]);
+      const mergeResult = await runGitChecked(existingPath, ["merge", "--ff-only", baseHead]);
+      if (mergeResult.success) {
         await bindReviewWorktreeRefs(item, existingPath, branch, state);
-      else
-        await bindWorktreeRefs(item, existingPath, branch, state.baseBranch);
-      reused = true;
-    } else {
-      const clean = await isWorktreeClean(existingPath);
-      if (!clean) {
-        throw new Error(`已有 worktree "${existingPath}" 与 ${state.baseBranch} 分叉且有未提交变更，无法自动 fast-forward。
-` + `请手动处理后重试。`);
-      }
-      const localCommitCount = parseInt(await runGit(existingPath, ["rev-list", "--count", `${state.baseBranch}..HEAD`]), 10);
-      if (localCommitCount > 0 || Number.isNaN(localCommitCount)) {
-        if (isReview)
-          await bindReviewWorktreeRefs(item, existingPath, branch, state);
-        else
-          await bindWorktreeRefs(item, existingPath, branch, state.baseBranch);
         reused = true;
       } else {
-        const cleanup = await removeTaskGroupWorktree(repoRoot, existingPath, { branchName: branch });
-        if (!cleanup.dirResolved || cleanup.branchDeleted === false) {
-          const problems = [];
-          if (!cleanup.dirResolved)
-            problems.push(`无法清理已有 worktree "${existingPath}"`);
-          if (cleanup.branchDeleted === false)
-            problems.push(`无法清理已有分支 "${branch}"`);
-          throw new Error(`${problems.join("；")}：${cleanup.errors.join("；") || "原因未知"}
+        const clean = await isWorktreeClean(existingPath);
+        if (!clean) {
+          throw new Error(`已有 worktree "${existingPath}" 与 ${state.baseBranch} 分叉且有未提交变更，无法自动 fast-forward。
+` + `请手动处理后重试。`);
+        }
+        const localCommitCount = parseInt(await runGit(existingPath, ["rev-list", "--count", `${state.baseBranch}..HEAD`]), 10);
+        if (localCommitCount > 0 || Number.isNaN(localCommitCount)) {
+          await bindReviewWorktreeRefs(item, existingPath, branch, state);
+          reused = true;
+        } else {
+          const cleanup = await removeTaskGroupWorktree(repoRoot, existingPath, { branchName: branch });
+          if (!cleanup.dirResolved || cleanup.branchDeleted === false) {
+            const problems = [];
+            if (!cleanup.dirResolved)
+              problems.push(`无法清理已有 worktree "${existingPath}"`);
+            if (cleanup.branchDeleted === false)
+              problems.push(`无法清理已有分支 "${branch}"`);
+            throw new Error(`${problems.join("；")}：${cleanup.errors.join("；") || "原因未知"}
 请手动处理后重试。`);
+          }
         }
       }
     }
-  }
-  if (!reused) {
-    const forkBranch = state.baseBranch;
-    await runGit(repoRoot, ["worktree", "add", "-b", branch, wtPath, forkBranch]);
-    if (isReview) {
+    if (!reused) {
+      const forkBranch = state.baseBranch;
+      await runGit(repoRoot, ["worktree", "add", "-b", branch, wtPath, forkBranch]);
       await bindReviewWorktreeRefs(item, wtPath, branch, state);
       if (state.reviewScope?.scopeType === "pr" && !item.metadata["base_ref"]) {
         throw new Error(`worktree 创建成功但无法获取 ${state.reviewScope.baseRef} 与 ${state.baseBranch} 的 merge-base：${wtPath}`);
       }
-    } else {
-      await bindWorktreeRefs(item, wtPath, branch, forkBranch, { requireBaseRef: true });
     }
+  } else {
+    const ensured = await ensureChangeWorktree(repoRoot, state, item, branch, wtPath);
+    wtPath = ensured.path;
+    reused = ensured.reused;
   }
   await writeState(ctx.worktree, state);
   const storedPath = typeof item.metadata["worktree_path"] === "string" ? item.metadata["worktree_path"] : null;
@@ -28997,8 +29081,43 @@ function renderReviewIssueSummary(item) {
   return lines.join(`
 `);
 }
+function rollbackToCleanupStep(item, workflow) {
+  if (!workflow.stepMap.has("verify_cleanup"))
+    return false;
+  delete item.metadata["_advance_block_reason"];
+  delete item.metadata["_checkpoint"];
+  resetInternalRetryCount(item);
+  clearStepTags(item, "verify_cleanup");
+  delete item.metadata["scope_end_oid"];
+  item.phase = "review";
+  item.currentStep = "verify_cleanup";
+  return true;
+}
+function renderFinalizeBlocked(reasons, handlings, opts) {
+  const lines = [
+    `- **status**: blocked`,
+    ...reasons.map((r) => `- **原因**: ${r}`),
+    `- **说明**: worktree 与变更分支 \`${opts.branchName}\` 已保留；未执行合并，无半成品状态。属多 change 并行推进的预期行为。` + (opts.rolledBack ? "本任务组状态已回退到收尾验证（verify_cleanup）。" : ""),
+    ...handlings.map((h) => `- **处理**: ${h}`),
+    "",
+    "重新查询 opx_status 获取分派指引。"
+  ];
+  if (opts.checkboxWarning)
+    lines.push(opts.checkboxWarning);
+  return lines.join(`
+`);
+}
 async function completeTaskGroupExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_complete_task_group");
+  const lockPath = await getLockPath(ctx.worktree, params.change_id);
+  await acquireLock(lockPath);
+  try {
+    return await completeTaskGroupLocked(params, ctx);
+  } finally {
+    releaseLock(lockPath);
+  }
+}
+async function completeTaskGroupLocked(params, ctx) {
   const state = await readStateByWorktree(ctx.worktree, params.change_id);
   if (!state)
     throw new Error("编排会话未初始化。请先调用 opx_orch_init。");
@@ -29017,7 +29136,8 @@ async function completeTaskGroupExecute(params, ctx) {
     if (!clean)
       throw new Error(`worktree "${worktreePath}" 存在未 commit 内容，请先 commit 再完成任务组。`);
   }
-  const isReviewNone = state.kind === "review" && state.reviewScope?.fix === "none";
+  const isReview = state.kind === "review";
+  const isReviewNone = isReview && state.reviewScope?.fix === "none";
   const openIssues = item.children.filter((c) => isBlockingSeverity(c.severity) && !isTerminalPhase(c.phase));
   if (!isReviewNone && openIssues.length > 0) {
     throw new Error(`存在 ${openIssues.length} 个 Low 及以上的未解决 issue 未处理，请先修复或申请豁免。`);
@@ -29039,6 +29159,91 @@ async function completeTaskGroupExecute(params, ctx) {
       checkboxWarning = `- **tasks.md 复选框勾选失败**: ${e instanceof Error ? e.message : String(e)}（不影响收尾）`;
     }
   }
+  if (!isReview && worktreePath && branchName) {
+    const endOid = (await runGit(worktreePath, ["rev-parse", branchName])).trim();
+    if (endOid)
+      item.metadata["scope_end_oid"] = endOid;
+  }
+  if (isReview) {
+    return finalizeReviewSession(state, item, params, ctx, { worktreePath, branchName, isReviewNone, checkboxWarning });
+  }
+  if (!isFinalTaskGroup(state, item)) {
+    item.metadata["completed_at"] = new Date().toISOString();
+    await writeState(ctx.worktree, state);
+    const doneMessage = "任务组已完成。本任务组变更保留在 change 分支上，待全部任务组完成后统一收口合并（本次不合并、不销毁 worktree）。";
+    return checkboxWarning ? `${doneMessage}
+${checkboxWarning}` : doneMessage;
+  }
+  const mergeTarget = state.baseBranch;
+  if (branchName) {
+    await ensureChangeBranch(ctx.worktree, branchName, mergeTarget);
+    if (!await isAncestor(ctx.worktree, mergeTarget, branchName)) {
+      const workflow = loadWorkflowFile(resolveWorkflowPath(state));
+      const rolledBack = rollbackToCleanupStep(item, workflow);
+      if (rolledBack)
+        await writeState(ctx.worktree, state);
+      return renderFinalizeBlocked([
+        `基准分支 \`${mergeTarget}\` 已推进（与变更分支 \`${branchName}\` 存在漂移）：基准分支最新提交未包含在变更分支历史中，直接合并会遗漏基准分支新内容。`
+      ], [
+        `在 worktree 内执行 \`git merge ${mergeTarget}\` 合入基准分支最新代码并解决冲突，完成回归验证后重新提交收尾验证（opx_agent_submit，step_id="verify_cleanup"），通过后再调用 opx_orch_complete_task_group 重新收口。`
+      ], { branchName, mergeTarget, rolledBack, checkboxWarning });
+    }
+    const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget);
+    if (mergeResult.blockedMessage) {
+      return [`- **status**: blocked`, mergeResult.blockedMessage].join(`
+`);
+    }
+    if (!mergeResult.success) {
+      const workflow = loadWorkflowFile(resolveWorkflowPath(state));
+      const rolledBack = rollbackToCleanupStep(item, workflow);
+      if (rolledBack)
+        await writeState(ctx.worktree, state);
+      return renderFinalizeBlocked([
+        `变更分支 \`${branchName}\` 合并到 \`${mergeTarget}\` 时发生冲突，未产生任何变更（分支引用未动，无半成品合并）。`
+      ], [
+        `在 worktree 内执行 \`git merge ${mergeTarget}\` 合入基准分支最新代码解决冲突并提交，完成回归验证后重新提交收尾验证（opx_agent_submit，step_id="verify_cleanup"），通过后再调用 opx_orch_complete_task_group 重新收口。`
+      ], { branchName, mergeTarget, rolledBack, checkboxWarning });
+    }
+  }
+  let cleanupNote = "";
+  let cleanupResidualWarning = "";
+  if (worktreePath) {
+    const cleanup = await removeTaskGroupWorktree(ctx.worktree, worktreePath, { branchName });
+    if (cleanup.dirResolved) {
+      await sweepEmptyWorktreeParents(ctx.worktree, worktreePath, params.change_id);
+      const successNotes = [];
+      if (cleanup.dirResolvedByFallback) {
+        successNotes.push("- **cleanup**: git worktree remove 未直接移除目录，已按文件系统兜底删除并 prune 管理记录。");
+      }
+      if (cleanup.errors.length > 0) {
+        successNotes.push(`- **cleanup 部分告警**: ${cleanup.errors.join("；")}`);
+      }
+      cleanupNote = successNotes.join(`
+`);
+    } else {
+      item.metadata["cleanup_residual"] = { worktree_path: worktreePath, errors: cleanup.errors };
+      cleanupResidualWarning = [
+        "",
+        "## ⚠️ worktree 清理残留（不影响收口）",
+        `- **残留路径**: \`${worktreePath}\``,
+        "- **原因**:",
+        ...cleanup.errors.map((e) => `  - ${e}`),
+        `- **处理**: 请人工执行 \`rm -rf '${worktreePath}' && git worktree prune\` 清理残留目录与 git 管理记录。`,
+        branchName ? `- **分支**: 分支 "${branchName}" 未删除。` : ""
+      ].filter(Boolean).join(`
+`);
+    }
+  }
+  item.metadata["completed_at"] = new Date().toISOString();
+  await writeState(ctx.worktree, state);
+  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean);
+  const doneMessage = branchName ? `任务组已完成并合并到 "${mergeTarget}"。` : "任务组已完成（无变更分支引用，跳过合并）。";
+  return notes.length > 0 ? `${doneMessage}
+${notes.join(`
+`)}` : doneMessage;
+}
+async function finalizeReviewSession(state, item, params, ctx, refs) {
+  const { worktreePath, branchName, isReviewNone, checkboxWarning } = refs;
   const mergeTarget = state.baseBranch;
   if (branchName && !isReviewNone) {
     const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget);
@@ -29088,19 +29293,13 @@ async function completeTaskGroupExecute(params, ctx) {
   item.metadata["completed_at"] = new Date().toISOString();
   await writeState(ctx.worktree, state);
   const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean);
-  if (state.kind === "review") {
-    const summary = renderReviewIssueSummary(item);
-    const doneMessage = isReviewNone ? `独立审查会话已完成（只审模式，未合并，worktree 与分支已销毁）。` : `独立审查会话已完成并合并到 "${mergeTarget}"。`;
-    return notes.length > 0 ? `${doneMessage}
+  const summary = renderReviewIssueSummary(item);
+  const doneMessage = isReviewNone ? `独立审查会话已完成（只审模式，未合并，worktree 与分支已销毁）。` : `独立审查会话已完成并合并到 "${mergeTarget}"。`;
+  return notes.length > 0 ? `${doneMessage}
 ${notes.join(`
 `)}
 ${summary}` : `${doneMessage}
 ${summary}`;
-  }
-  const doneMessage = `任务组已完成并合并到 "${mergeTarget}"。`;
-  return notes.length > 0 ? `${doneMessage}
-${notes.join(`
-`)}` : doneMessage;
 }
 async function setUnattendedExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_set_unattended");
@@ -29913,13 +30112,13 @@ var orchInitSchema = {
     },
     base_branch: {
       type: "string",
-      description: "基准分支名（如 main、develop），用于计算 merge-base 和 worktree fork 源。未传则自动从当前 git 分支推导。仅 change 会话入口有效。"
+      description: "基准分支名（如 main、develop），作为 change 分支（change/{changeId}）的 fork 源与收口合并目标。未传则自动从当前 git 分支推导。仅 change 会话入口有效。"
     },
     recovery: recoverySchema,
     mode: {
       type: "string",
       enum: ["full", "simple"],
-      description: "流程模式选择（仅 change 会话入口有效，独立审查会话不使用）：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。"
+      description: "流程模式选择（仅 change 会话入口有效，独立审查会话不使用）：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，verify_cleanup 仅作收口漂移/冲突回退落点，正常流转不经过，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。"
     },
     review_scope: {
       type: "object",
@@ -29961,8 +30160,8 @@ var setWorktreeSchema = {
   type: "object",
   properties: {
     change_id: { type: "string", minLength: 1, description: "change ID" },
-    worktree_path: { type: "string", description: "git worktree 的绝对路径（可选，不传则按规范自动生成）" },
-    branch_name: { type: "string", description: "worktree 对应的分支名（可选，不传则按规范 task-group/{changeId}/{taskGroupId}）" }
+    worktree_path: { type: "string", description: "git worktree 的绝对路径（可选，不传则按规范自动生成 .worktree/{changeId}/ws）" },
+    branch_name: { type: "string", description: "worktree 对应的分支名（可选，不传则按 change 模型确定性派生：change/{changeId}，整个 change 串行复用同一分支与常驻 worktree）" }
   },
   required: ["change_id"],
   additionalProperties: false
@@ -30151,7 +30350,7 @@ var TOOL_SPECS = {
     execute: (args, ctx) => initExecute(args, ctx)
   },
   opx_orch_set_worktree: {
-    description: "确保目标组的 git worktree 就绪。若已存在则复用，否则按规范自动创建（分支 task-group/{changeId}/{taskGroupId}，路径 .worktree/{changeId}/task-group-{taskGroupId}）。只补齐资源，不改变阶段。",
+    description: "确保目标组的 git worktree 就绪。change 会话按 change 模型 create-or-reuse：分支 change/{changeId} 不存在时从基准分支 tip 创建，worktree 常驻于 .worktree/{changeId}/ws，全部任务组串行复用（复用校验：目录缺失自愈重建、openspec 文档脏自动提交、代码文件脏拒绝）。只补齐资源，不改变阶段。",
     schema: setWorktreeSchema,
     execute: (args, ctx) => setWorktreeExecute(args, ctx)
   },
@@ -30161,7 +30360,7 @@ var TOOL_SPECS = {
     execute: (args, ctx) => statusExecute({ change_id: args.change_id }, ctx)
   },
   opx_orch_complete_task_group: {
-    description: "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突、主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
+    description: "完成任务组收尾。非最后任务组仅做门禁与范围标记（不合并、不销毁）；最后一个任务组收口时把 change 分支（change/{changeId}）一次性合并回 baseBranch（基准分支漂移或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 worktree 并删分支。须在收尾验证（verify_cleanup）通过后调用。主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
     schema: completeTaskGroupSchema,
     execute: (args, ctx) => completeTaskGroupExecute(args, ctx)
   },
@@ -30206,7 +30405,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.135.0";
+var PKG_VERSION = "0.137.0";
 function buildMcpServer(worktree, opts = {}) {
   const mcp = new McpServer({ name: "openspec-agents", version: PKG_VERSION });
   for (const [name, spec] of Object.entries(TOOL_SPECS)) {

package/README.md

@@ -14,7 +14,7 @@
 - **提案标准化**：内置 OpenSpec 提案标准（关联场景清点、契约变更详列、动笔前访谈与用户确认），一键初始化到任意项目，在提 change 阶段防漏考虑、防拆分割裂。
 - **智能体团队**：不再是单个 AI 从头写到尾，而是「实现者 + 审查者 + 质量把关者」分工协作，结果更稳。
 - **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。任务验证层（任务审查 / 合并审查）以通过（passed）提交时必须逐项确认全部已申报任务（verified_tasks 全覆盖为工具强制门禁）；已通过但漏带确认导致阻塞时，审查者可补交确认结果解除阻塞。simple 模式下验证按性质分流——开发者执行确定性检查并申报，审查者分级复验（低成本项实跑、高成本项核验申报加抽样重放）并专注对抗性判断。
-- **隔离执行**：每个变更在独立的环境中实施，互不干扰；变更完成后合并并清理。
+- **隔离执行**：每个变更使用一条独立分支 `change/{changeId}` 与一个常驻 worktree（`.worktree/{changeId}/ws`），全部任务组在同一 worktree 内串行实施，互不干扰；收口合并前主仓库基准分支上看不到该变更代码（change 级进度可用 `git log change/{changeId}` 查看），完成后统一合并并清理。
 - **过程可审计**：进度、结论、豁免与恢复点全程记录，随时可以接着上次的进度继续。人工执行或环境不可验证的任务经 blocker 上报、用户确认留痕（blocker_updates）后凭记录申报完成；恢复参数 reset_steps 按流程模式（full / simple）校验各自的审查步骤值域后生效。
 
 ## 快速开始
@@ -92,7 +92,8 @@ npm install -D @ifrankwang/openspec-agents
 1. **输入**：项目中的 OpenSpec 变更规范（变更说明、设计、任务清单、验收规格）。
 2. **分派**：主智能体把任务交给专职智能体——实现者负责写代码，审查者负责检查，质量把关者负责多维验证。
 3. **门禁**：每一步的结论通过检查后才进入下一步；不通过的结论自动回到实现环节修复。
-4. **收尾**：变更完成后自动合并分支并清理执行环境；change 的全部任务组完成后，主智能体按状态视图指引汇总部署注意事项（规划文档提取 + 开发者实施补充点）向用户汇报。全程留痕可审计。
+4. **收尾合并**：任务组完成只做门禁校验并标记变更范围，不合并、不销毁 worktree；最后一个任务组收口时把 change 分支一次性合并回基准分支，随后销毁 worktree 并删除 change 分支。合并前若基准分支已推进，先做基线漂移检查，发现漂移或冲突则把该任务组回退到收尾验证环节（合并基准分支最新代码并回归复验）后再收口——验收仅在漂移时动态发生，正常路径零额外环节。
+5. **部署注意事项**：change 的全部任务组完成后，主智能体按状态视图指引汇总部署注意事项（规划文档提取 + 开发者实施补充点，含依赖清单/构建配置变更等合并后需在主仓库重装依赖、重新构建的事项）向用户汇报。全程留痕可审计。
 
 ## 独立审查会话
 

package/assets/skills/openspec-standard/templates/openspec/config.yaml

@@ -15,7 +15,7 @@ rules:
     - "关联场景清点（强制）：proposal 动笔前必须完成「关联场景清点」并以代码检索为证据记入 clarify.md 的「关联场景清点（Related-Surface Survey）」小节：枚举本变更触及能力的全部消费方与关联面——功能入口（API 端点、导入/导出入口、定时任务、消息消费、前端调用等）、共享处理逻辑（被多个入口复用的处理链路）、数据模型与数据流下游（表/字段/事件/导出产物的读写双方），每条附代码位置证据（文件/类/方法）。凡共享处理逻辑发生变更，其全部消费入口必须在同一 change 内统一适配，禁止按入口分别提 change 导致共享逻辑两边割裂维护；确需拆分时必须在 proposal.md 单列「拆分边界」小节论证（每个 change 覆盖哪些入口、共享逻辑变更归属哪个 change、入口间契约），并经用户确认。proposal.md 必须单列「关联场景（Related Surface）」小节逐条列出清点结论与划界结论；泛写「无关联影响」而不附检索证据视为 proposal 未完成。"
     - "契约变更详列（强制）：凡变更涉及 DDL（建表/加列/索引/约束）或接口契约（新增/修改端点、请求响应结构、错误码），proposal.md 必须单列「契约变更点」小节逐条列出——DDL 逐表逐列给全表名、列名、类型、可空性、默认值与用途；API 逐端点给全方法+路径、请求/响应结构变化、新增/修改标记与兼容性影响。泛写「有契约变更」不逐条展开视为 proposal 未完成。"
     - "动笔前访谈门（强制）：proposal/specs/design/tasks 任一文档动笔前，必须已按 spec-driven-standard schema clarify 指令的决策树访谈方法论完成对用户的访谈——把方案建模为决策树逐轮穷尽疑点：每轮将前提已落定、当前可回答的问题一次性编号抛出并逐题附推荐答案，用户答复后重算下一轮前沿，直到决策树所有分支走完、无未决疑点、无静默假设；访谈问答全程记入 clarify.md（Open Questions / User Answers / 关联场景清点）。事实类问题必须自行查代码与 spec 求证，不抛给用户；疑点未穷尽时禁止写任何文档，不得以「需求简单」等理由跳过。"
-    - "动笔前用户确认门（强制）：proposal/specs/design/tasks 任一文档动笔前，clarify.md 的 Architecture Direction 必须已记录用户对方案摘要的明确确认；未记录时禁止写任何文档——主代理亲自写时先停下向用户补确认，生成子代理则立即终止并向编排方报告，不得以「需求简单」等理由跳过或代用户确认。"
+    - "动笔前用户确认门（强制）：proposal/specs/design/tasks 任一文档动笔前，clarify.md 的 Architecture Direction 必须已记录用户对方案摘要的明确确认；确认必须以普通消息直接列出方案摘要要素点（要素清单见 spec-driven-standard schema clarify 指令的 Plan confirmation gate）并停下等待用户直接文字回复，禁止通过提问工具发起确认，提问工具的选项点击不视为确认；未记录时禁止写任何文档——主代理亲自写时先停下向用户补确认，生成子代理则立即终止并向编排方报告，不得以「需求简单」等理由跳过或代用户确认。"
   specs:
     - "数据行为需求（如\"系统 SHALL 持久化 X 含审计字段\"）放 spec；物理 DDL 放 design.md。"
     - "MODIFIED 的需求描述直接给出变更后的终态契约表述（\"系统 SHALL 使用 Y\"），供归档合并时原样落入主 spec；禁止以\"原 X 改为 Y\"的历史对比充当主 spec 内容。"

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/README.md

@@ -6,8 +6,9 @@
    （枚举变更触及能力的全部消费方——功能入口 / 共享处理逻辑 / 数据流下游，
    附代码证据；共享处理逻辑变更须与其全部消费入口同一 change 统一适配）；
    访谈结束后、写任何文档之前，主代理必须先向用户简单直接汇报方案（一句话
-   讲清做什么 + 是否动契约 + 取舍 + 影响面）并取得用户明确确认（HARD-GATE，
-   访谈中的问答不视为确认），确认记录落在 clarify.md，后续文档不得偏离。
+   讲清做什么 + 是否动契约 + 取舍 + 影响面）并取得用户明确确认（HARD-GATE：
+   汇报须以普通消息直接列出要素点，禁止用提问工具发起确认，访谈中的问答
+   不视为确认），确认记录落在 clarify.md，后续文档不得偏离。
 2. **主代理访谈直录 + 分级撰写 + 独立复核循环**：主代理亲自访谈，问答
    直接记入 clarify.md（访谈阶段唯一落笔的文档，不设独立访谈文件）；
    架构方向经用户确认后，按复杂度分级产出其余文档（proposal → specs →