@ifrankwang/openspec-agents 0.137.0 → 0.138.0

package/.mcp-server/cli.mjs

@@ -21671,6 +21671,12 @@ async function isAncestor(worktree, a, b) {
     return false;
   throw new Error(`无法判断 "${a}" 是否为 "${b}" 的祖先：${r.stderr}`);
 }
+async function listBranchDriftFiles(worktree, sourceBranch, targetBranch) {
+  const r = await runGitChecked(worktree, ["diff", "--name-only", "--no-renames", `${sourceBranch}...${targetBranch}`]);
+  if (!r.success)
+    return null;
+  return parseDiffNameOnly(r.stdout);
+}
 async function isLocalBranch(worktree, branch) {
   const r = await runGitChecked(worktree, ["rev-parse", "--verify", `refs/heads/${branch}`]);
   return r.success;
@@ -29081,6 +29087,12 @@ function renderReviewIssueSummary(item) {
   return lines.join(`
 `);
 }
+var DOCUMENTATION_EXTENSIONS = [".md", ".mdx", ".markdown", ".rst", ".adoc"];
+function isDocumentationOnly(files) {
+  if (files === null)
+    return false;
+  return files.every((f) => DOCUMENTATION_EXTENSIONS.some((ext) => f.endsWith(ext)));
+}
 function rollbackToCleanupStep(item, workflow) {
   if (!workflow.stepMap.has("verify_cleanup"))
     return false;
@@ -29175,18 +29187,25 @@ async function completeTaskGroupLocked(params, ctx) {
 ${checkboxWarning}` : doneMessage;
   }
   const mergeTarget = state.baseBranch;
+  let docDriftNote = "";
   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 driftFiles = await listBranchDriftFiles(ctx.worktree, branchName, mergeTarget);
+      if (!isDocumentationOnly(driftFiles)) {
+        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 files = driftFiles ?? [];
+      const driftList = files.length > 10 ? `${files.slice(0, 10).join(", ")} 等 ${files.length} 个` : files.join(", ");
+      docDriftNote = `- **基准漂移（纯文档）**: 基准分支 \`${mergeTarget}\` 相对变更分支切出点净变化 ${files.length} 个文件` + (files.length > 0 ? `（${driftList}）` : "") + "，均为文档，不影响代码语义，未回退收尾验证直接合并。";
     }
     const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget);
     if (mergeResult.blockedMessage) {
@@ -29236,7 +29255,7 @@ ${checkboxWarning}` : doneMessage;
   }
   item.metadata["completed_at"] = new Date().toISOString();
   await writeState(ctx.worktree, state);
-  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean);
+  const notes = [docDriftNote, cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean);
   const doneMessage = branchName ? `任务组已完成并合并到 "${mergeTarget}"。` : "任务组已完成（无变更分支引用，跳过合并）。";
   return notes.length > 0 ? `${doneMessage}
 ${notes.join(`
@@ -30360,7 +30379,7 @@ var TOOL_SPECS = {
     execute: (args, ctx) => statusExecute({ change_id: args.change_id }, ctx)
   },
   opx_orch_complete_task_group: {
-    description: "完成任务组收尾。非最后任务组仅做门禁与范围标记（不合并、不销毁）；最后一个任务组收口时把 change 分支（change/{changeId}）一次性合并回 baseBranch（基准分支漂移或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 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)
   },
@@ -30405,7 +30424,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.137.0";
+var PKG_VERSION = "0.138.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

@@ -92,7 +92,7 @@ npm install -D @ifrankwang/openspec-agents
 1. **输入**：项目中的 OpenSpec 变更规范（变更说明、设计、任务清单、验收规格）。
 2. **分派**：主智能体把任务交给专职智能体——实现者负责写代码，审查者负责检查，质量把关者负责多维验证。
 3. **门禁**：每一步的结论通过检查后才进入下一步；不通过的结论自动回到实现环节修复。
-4. **收尾合并**：任务组完成只做门禁校验并标记变更范围，不合并、不销毁 worktree；最后一个任务组收口时把 change 分支一次性合并回基准分支，随后销毁 worktree 并删除 change 分支。合并前若基准分支已推进，先做基线漂移检查，发现漂移或冲突则把该任务组回退到收尾验证环节（合并基准分支最新代码并回归复验）后再收口——验收仅在漂移时动态发生，正常路径零额外环节。
+4. **收尾合并**：任务组完成只做门禁校验并标记变更范围，不合并、不销毁 worktree；最后一个任务组收口时把 change 分支一次性合并回基准分支，随后销毁 worktree 并删除 change 分支。合并前若基准分支已推进，先做基线漂移检查并比对基准侧净变化内容：纯文档变化（md / mdx / markdown / rst / adoc 五类后缀）不影响代码语义，直接合并收口；含任一非文档文件或文本冲突才把该任务组回退到收尾验证环节（合并基准分支最新代码并回归复验）后再收口——验收仅在实质漂移时动态发生，正常路径零额外环节。
 5. **部署注意事项**：change 的全部任务组完成后，主智能体按状态视图指引汇总部署注意事项（规划文档提取 + 开发者实施补充点，含依赖清单/构建配置变更等合并后需在主仓库重装依赖、重新构建的事项）向用户汇报。全程留痕可审计。
 
 ## 独立审查会话

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.137.0",
+  "version": "0.138.0",
   "description": "OpenSpec change orchestration plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode)",
   "author": "ifrankwang",
   "license": "MIT",

package/src/adapters/mcp-common/server.ts

@@ -55,7 +55,7 @@ const TOOL_SPECS: Record<string, ToolSpec> = {
   },
   opx_orch_complete_task_group: {
     description:
-      "完成任务组收尾。非最后任务组仅做门禁与范围标记（不合并、不销毁）；最后一个任务组收口时把 change 分支（change/{changeId}）一次性合并回 baseBranch（基准分支漂移或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 worktree 并删分支。须在收尾验证（verify_cleanup）通过后调用。主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
+      "完成任务组收尾。非最后任务组仅做门禁与范围标记（不合并、不销毁）；最后一个任务组收口时把 change 分支（change/{changeId}）一次性合并回 baseBranch（漂移含任一非文档文件或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked，纯文档漂移直接合并收口），成功后销毁 worktree 并删分支。须在收尾验证（verify_cleanup）通过后调用。主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
     schema: completeTaskGroupSchema,
     execute: (args, ctx) => completeTaskGroupExecute(args as any, ctx),
   },

package/src/core/git.ts

@@ -169,6 +169,16 @@ export async function isAncestor(worktree: string, a: string, b: string): Promis
   throw new Error(`无法判断 "${a}" 是否为 "${b}" 的祖先：${r.stderr}`)
 }
 
+/** 查询基准侧漂移文件清单：`git diff --name-only --no-renames <sourceBranch>...<targetBranch>`
+ *  三点区间 = merge-base(source, target) 到 target 的内容差异（基准侧自分支切出点以来的净变化，非 commit 口径）。
+ *  参数方向固定：source 传变更分支，target 传基准分支（切出点在 source 一侧）。
+ *  返回 null 表示 git 查询失败，调用方须按非文档保守回退。 */
+export async function listBranchDriftFiles(worktree: string, sourceBranch: string, targetBranch: string): Promise<string[] | null> {
+  const r = await runGitChecked(worktree, ["diff", "--name-only", "--no-renames", `${sourceBranch}...${targetBranch}`])
+  if (!r.success) return null
+  return parseDiffNameOnly(r.stdout)
+}
+
 /** 校验本地分支存在（refs/heads/<name> 严格本地命名空间，不含远端跟踪 ref）。 */
 export async function isLocalBranch(worktree: string, branch: string): Promise<boolean> {
   const r = await runGitChecked(worktree, ["rev-parse", "--verify", `refs/heads/${branch}`])

package/src/core/tools/lifecycle.ts

@@ -3,7 +3,7 @@ import { rmdir } from "node:fs/promises"
 import type { OrchestrateState, TaskItem, TaskStatus, WorkflowMode, ReviewScope } from "../types.ts"
 import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS, SIMPLE_REVIEW_STEPS, REVIEW_TASK_GROUP_ID } from "../types.ts"
 import { agentToReviewLayer } from "../constants.ts"
-import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isAncestor, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, removeTaskGroupWorktree, isLocalBranch, listLocalBranches, pathExists, type DetectChangesResult } from "../git.ts"
+import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isAncestor, isWorktreeClean, listBranchDriftFiles, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, removeTaskGroupWorktree, isLocalBranch, listLocalBranches, pathExists, type DetectChangesResult } from "../git.ts"
 import { readStateByWorktree, readStateByChangeId, writeState, writeContextToWorktree, getLockPath, acquireLock, releaseLock } from "../state.ts"
 import { generateIsolationNamespace } from "../namespace.ts"
 import { readExemptions } from "../exemptions.ts"
@@ -1193,6 +1193,14 @@ function renderReviewIssueSummary(item: WorkItem): string {
   return lines.join("\n")
 }
 
+/** 漂移内容纯文档判定：null（查询失败）按非文档保守回退；空清单 = 内容无净变化（如基准上改了又回滚）视为纯文档；
+ *  全部文件后缀属文档格式才放行。.txt 刻意排除（requirements.txt 等依赖清单具代码语义）。 */
+const DOCUMENTATION_EXTENSIONS = [".md", ".mdx", ".markdown", ".rst", ".adoc"]
+function isDocumentationOnly(files: string[] | null): boolean {
+  if (files === null) return false
+  return files.every((f) => DOCUMENTATION_EXTENSIONS.some((ext) => f.endsWith(ext)))
+}
+
 /**
  * 最后任务组收口被基准分支漂移/文本冲突拦截时的回退：
  * 该任务组回退到收尾验证（verify_cleanup）等待重新收口——phase 回退 + clearStepTags + 按 recovery
@@ -1321,24 +1329,38 @@ async function completeTaskGroupLocked(params: { change_id: string }, ctx: ToolC
 
   // 最后任务组 → change 级收口：合并 change 分支回基准分支（一次性），成功后销毁 worktree 并删分支
   const mergeTarget = state.baseBranch
+  // 纯文档漂移直通时的事实说明：仅在本次收口实际发生直通时非空；合并 blocked/conflict 分支不带该说明
+  let docDriftNote = ""
   if (branchName) {
     // create-or-reuse（合并目标解析前）：在途旧模型会话升级时从当前基准 tip 创建，天然含已合入代码
     await ensureChangeBranch(ctx.worktree, branchName, mergeTarget)
 
-    // 前置漂移检查（独立封装）：基准 tip 须为 change 分支祖先；不满足 → 回退收尾验证并 blocked
+    // 前置漂移检查（独立封装）：基准 tip 须为 change 分支祖先；不满足时先比对基准侧净变化内容——
+    // 纯文档漂移（含空清单 = 无净变化）不回退、直接合并收口；含任一非文档文件或清单查询失败 → 回退收尾验证并 blocked
     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 driftFiles = await listBranchDriftFiles(ctx.worktree, branchName, mergeTarget)
+      if (!isDocumentationOnly(driftFiles)) {
+        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 files = driftFiles ?? []
+      const driftList = files.length > 10
+        ? `${files.slice(0, 10).join(", ")} 等 ${files.length} 个`
+        : files.join(", ")
+      docDriftNote =
+        `- **基准漂移（纯文档）**: 基准分支 \`${mergeTarget}\` 相对变更分支切出点净变化 ${files.length} 个文件` +
+        (files.length > 0 ? `（${driftList}）` : "") +
+        "，均为文档，不影响代码语义，未回退收尾验证直接合并。"
     }
 
     const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget)
@@ -1394,7 +1416,7 @@ async function completeTaskGroupLocked(params: { change_id: string }, ctx: ToolC
   }
   item.metadata["completed_at"] = new Date().toISOString()
   await writeState(ctx.worktree, state)
-  const notes = [cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean)
+  const notes = [docDriftNote, cleanupNote, checkboxWarning, cleanupResidualWarning].filter(Boolean)
   const doneMessage = branchName
     ? `任务组已完成并合并到 "${mergeTarget}"。`
     : "任务组已完成（无变更分支引用，跳过合并）。"