@ifrankwang/openspec-agents 0.140.0 → 0.142.0

package/.mcp-server/cli.mjs

@@ -21677,6 +21677,19 @@ async function listBranchDriftFiles(worktree, sourceBranch, targetBranch) {
     return null;
   return parseDiffNameOnly(r.stdout);
 }
+async function isVersionOnlyDrift(worktree, sourceBranch, targetBranch, filePath) {
+  const r = await runGitChecked(worktree, ["diff", "--no-renames", `${sourceBranch}...${targetBranch}`, "--", filePath]);
+  if (!r.success)
+    return null;
+  for (const line of r.stdout.split(`
+`)) {
+    if (line.startsWith("+++") || line.startsWith("---"))
+      continue;
+    if ((line.startsWith("+") || line.startsWith("-")) && !/^[+-]\s*"version"\s*:/.test(line))
+      return false;
+  }
+  return true;
+}
 async function isLocalBranch(worktree, branch) {
   const r = await runGitChecked(worktree, ["rev-parse", "--verify", `refs/heads/${branch}`]);
   return r.success;
@@ -29093,10 +29106,27 @@ function renderReviewIssueSummary(item) {
 `);
 }
 var DOCUMENTATION_EXTENSIONS = [".md", ".mdx", ".markdown", ".rst", ".adoc"];
-function isDocumentationOnly(files) {
+var DRIFT_NEUTRAL_PATH_PREFIXES = ["openspec/"];
+async function isHarmlessDrift(worktree, sourceBranch, targetBranch, files) {
   if (files === null)
     return false;
-  return files.every((f) => DOCUMENTATION_EXTENSIONS.some((ext) => f.endsWith(ext)));
+  const versionCandidates = [];
+  for (const f of files) {
+    if (DOCUMENTATION_EXTENSIONS.some((ext) => f.endsWith(ext)))
+      continue;
+    if (DRIFT_NEUTRAL_PATH_PREFIXES.some((p) => f.startsWith(p)))
+      continue;
+    if (f === "package.json" || f.endsWith("/package.json")) {
+      versionCandidates.push(f);
+      continue;
+    }
+    return false;
+  }
+  for (const f of versionCandidates) {
+    if (await isVersionOnlyDrift(worktree, sourceBranch, targetBranch, f) !== true)
+      return false;
+  }
+  return true;
 }
 function rollbackToCleanupStep(item, workflow) {
   if (!workflow.stepMap.has("verify_cleanup"))
@@ -29197,7 +29227,7 @@ ${checkboxWarning}` : doneMessage;
     await ensureChangeBranch(ctx.worktree, branchName, mergeTarget);
     if (!await isAncestor(ctx.worktree, mergeTarget, branchName)) {
       const driftFiles = await listBranchDriftFiles(ctx.worktree, branchName, mergeTarget);
-      if (!isDocumentationOnly(driftFiles)) {
+      if (!await isHarmlessDrift(ctx.worktree, branchName, mergeTarget, driftFiles)) {
         const workflow = loadWorkflowFile(resolveWorkflowPath(state));
         const rolledBack = rollbackToCleanupStep(item, workflow);
         if (rolledBack)
@@ -29210,7 +29240,7 @@ ${checkboxWarning}` : doneMessage;
       }
       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}）` : "") + "，均为文档，不影响代码语义，未回退收尾验证直接合并。";
+      docDriftNote = `- **基准漂移（无代码语义）**: 基准分支 \`${mergeTarget}\` 相对变更分支切出点净变化 ${files.length} 个文件` + (files.length > 0 ? `（${driftList}）` : "") + "，均为文档、openspec 规划路径或仅版本号变更，不影响代码语义，未回退收尾验证直接合并。";
     }
     const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget);
     if (mergeResult.blockedMessage) {
@@ -30384,7 +30414,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（漂移无害——文档、openspec 规划路径或仅版本号变更的 package.json——时直接合并收口；漂移含任一其他文件或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 worktree 并删分支。须在收尾验证（verify_cleanup）通过后调用。主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
     schema: completeTaskGroupSchema,
     execute: (args, ctx) => completeTaskGroupExecute(args, ctx)
   },
@@ -30429,7 +30459,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.140.0";
+var PKG_VERSION = "0.142.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 分支。合并前若基准分支已推进，先做基线漂移检查并比对基准侧净变化内容：纯文档变化（md / mdx / markdown / rst / adoc 五类后缀）不影响代码语义，直接合并收口；含任一非文档文件或文本冲突才把该任务组回退到收尾验证环节（合并基准分支最新代码并回归复验）后再收口——验收仅在实质漂移时动态发生，正常路径零额外环节。
+4. **收尾合并**：任务组完成只做门禁校验并标记变更范围，不合并、不销毁 worktree；最后一个任务组收口时把 change 分支一次性合并回基准分支，随后销毁 worktree 并删除 change 分支。合并前若基准分支已推进，先做基线漂移检查并比对基准侧净变化内容：无害漂移不影响代码语义，直接合并收口——无害指三类之一：文档后缀变化（md / mdx / markdown / rst / adoc）、openspec/ 规划路径下的文档（提案/设计/任务/spec，不限后缀）、package.json 且变更内容仅版本号行；含任一其他文件或文本冲突才把该任务组回退到收尾验证环节（合并基准分支最新代码并回归复验）后再收口——验收仅在实质漂移时动态发生，正常路径零额外环节。
 5. **部署注意事项**：change 的全部任务组完成后，主智能体按状态视图指引汇总部署注意事项（规划文档提取 + 开发者实施补充点，含依赖清单/构建配置变更等合并后需在主仓库重装依赖、重新构建的事项）向用户汇报。全程留痕可审计。
 
 ## 独立审查会话

package/assets/skills/openspec-standard/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: openspec-standard
-description: OpenSpec 提案标准初始化与升级——把标准版提案规则（openspec/config.yaml + spec-driven-standard schema 全套）安装到当前项目，统一后续提 change 的质量门槛（关联场景清点、契约变更详列、动笔前访谈与用户确认）。当用户要求初始化、升级或标准化 openspec 提案标准/提案规范时使用。
+description: OpenSpec 提案标准初始化与升级——把标准版提案规则（openspec/config.yaml + spec-driven-standard schema 全套）安装到当前项目，统一后续提 change 的质量门槛（关联场景清点、契约变更详列、人话实施逻辑、结构化方案摘要、动笔前访谈与用户确认）。当用户要求初始化、升级或标准化 openspec 提案标准/提案规范时使用。
 capabilities: ["openspec-standard"]
 ---
 
 ## 职责
 
-把本 skill 目录 `templates/` 下的标准文件安装到当前项目的 `openspec/` 目录，使该项目此后用 openspec 提 change 时自动遵循统一标准：关联场景清点（共享处理逻辑的变更须与其全部消费入口同一 change 统一适配）、契约变更详列、动笔前访谈门与用户确认门、任务组实质变更主体等。幂等：重跑即把标准升级到插件当前版本，项目自定义内容按下方合并策略保留。
+把本 skill 目录 `templates/` 下的标准文件安装到当前项目的 `openspec/` 目录，使该项目此后用 openspec 提 change 时自动遵循统一标准：关联场景清点（共享处理逻辑的变更须与其全部消费入口同一 change 统一适配，同一数据多条落库路径的校验一致性为访谈必问分支）、契约变更详列、实施逻辑人话分步（proposal 单列实施逻辑小节，禁代码级名词）、结构化方案摘要（访谈穷尽后才给出、以普通消息确认）、动笔前访谈门与用户确认门、任务组实质变更主体等。幂等：重跑即把标准升级到插件当前版本，项目自定义内容按下方合并策略保留。
 
 ## 前置检查
 

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

@@ -14,7 +14,8 @@ rules:
   proposal:
     - "关联场景清点（强制）：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 任一文档动笔前，必须已按 spec-driven-standard schema clarify 指令的决策树访谈方法论完成对用户的访谈——把方案建模为决策树逐轮穷尽疑点：每轮将前提已落定、当前可回答的问题一次性编号抛出并逐题附推荐答案，用户答复后重算下一轮前沿，直到决策树所有分支走完、无未决疑点、无静默假设、关联场景清点每个条目均经用户划界确认（纳入/排除+理由）；访谈问答全程记入 clarify.md（Open Questions / User Answers / 关联场景清点）。事实类问题必须自行查代码与 spec 求证，不抛给用户；疑点未穷尽时禁止写任何文档，不得以「需求简单」等理由跳过。访谈未穷尽（含关联场景清点尚有未经用户划界确认的条目）时同样禁止呈现方案或方案摘要请求确认——轮次中每题附的推荐答案不视为方案，不得把方案确认合并进任何一轮提问；用户中途索要方案时说明访谈未完并继续提问，不得提前收口。"
+    - "实施逻辑与方案摘要结构（强制）：proposal.md 必须单列「实施逻辑（Implementation Outline）」小节，按步骤用业务语言（人话）讲清具体怎么做——数据从哪来、经过什么校验与处理、落到哪、关联场景小节划入的每条链路怎么适配；禁止出现类名/方法名/内部函数名等代码级名词（用户明确要求技术深度时除外；契约变更点小节的表名/列名/端点路径等契约事实不受此限、保持精确）。方案摘要必须按 spec-driven-standard schema clarify 指令 Plan confirmation gate 的要素清单结构化逐项展开（含人话分步实施逻辑与关联链路划界结论），两三句话的摘要视为未完成。"
     - "动笔前用户确认门（强制）：proposal/specs/design/tasks 任一文档动笔前，clarify.md 的 Architecture Direction 必须已记录用户对方案摘要的明确确认；确认必须以普通消息直接列出方案摘要要素点（要素清单见 spec-driven-standard schema clarify 指令的 Plan confirmation gate）并停下等待用户直接文字回复，禁止通过提问工具发起确认，提问工具的选项点击不视为确认；未记录时禁止写任何文档——主代理亲自写时先停下向用户补确认，生成子代理则立即终止并向编排方报告，不得以「需求简单」等理由跳过或代用户确认。"
   specs:
     - "数据行为需求（如\"系统 SHALL 持久化 X 含审计字段\"）放 spec；物理 DDL 放 design.md。"

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

@@ -3,12 +3,18 @@
 通用 spec-driven 工作流模板：clarify → proposal → specs → design → tasks，
 增强三点：
 1. **clarify 前置门槛 + 关联场景清点**：每次变更先做需求澄清与关联场景清点
-   （枚举变更触及能力的全部消费方——功能入口 / 共享处理逻辑 / 数据流下游，
-   附代码证据；共享处理逻辑变更须与其全部消费入口同一 change 统一适配）；
-   访谈结束后、写任何文档之前，主代理必须先向用户简单直接汇报方案（一句话
-   讲清做什么 + 是否动契约 + 取舍 + 影响面）并取得用户明确确认（HARD-GATE：
-   汇报须以普通消息直接列出要素点，禁止用提问工具发起确认，访谈中的问答
-   不视为确认），确认记录落在 clarify.md，后续文档不得偏离。
+   （首轮提问前枚举变更触及能力的全部消费方——功能入口 / 共享处理逻辑 /
+   数据流下游，附代码证据；每个清点条目在访谈中经用户划界确认——纳入本
+   change 统一适配或排除附理由；同一数据存在多条落库路径时各路径校验与
+   处理逻辑的一致性为必问分支；共享处理逻辑变更须与其全部消费入口同一
+   change 统一适配）；访谈穷尽后、写任何文档之前，主代理必须先向用户汇报
+   结构化方案摘要（按要素清单逐项编号展开：一句话做什么 + 是否动契约 +
+   选定方案与备选取舍 + 人话分步实施逻辑 + 关联链路划界结论 + 影响的能力
+   面）并取得用户明确确认（HARD-GATE：摘要须以普通消息呈现，禁止用提问
+   工具发起确认，访谈中的问答不视为确认；访谈未穷尽禁止呈现方案求确认，
+   轮次中每题附的推荐答案不视为方案），确认记录落在 clarify.md，后续文档
+   不得偏离。proposal.md 单列「实施逻辑」小节，以人话分步讲清怎么做（禁
+   代码级名词，契约事实除外），代码级细节归 design.md。
 2. **主代理访谈直录 + 分级撰写 + 独立复核循环**：主代理亲自访谈，问答
    直接记入 clarify.md（访谈阶段唯一落笔的文档，不设独立访谈文件）；
    架构方向经用户确认后，按复杂度分级产出其余文档（proposal → specs →
@@ -67,8 +73,8 @@ openspec/schemas/<schema-name>/
 
 | 位置 | 承载内容 | 例子 |
 |---|---|---|
-| `schema.yaml` instruction | 生成方法论与文档格式要求（官方方法论为底） | 场景标题 4 个 #、SHALL/MUST、ADDED/MODIFIED/REMOVED、任务组格式、每组自带测试与质量门、关联场景清点维度 |
-| `openspec/config.yaml` rules | **仅** schema 未覆盖的项目补充规则 | MODIFIED 终态契约表述、同语义一条需求、前置 change 标注格式、契约变更详列、访谈门与用户确认门 |
+| `schema.yaml` instruction | 生成方法论与文档格式要求（官方方法论为底） | 场景标题 4 个 #、SHALL/MUST、ADDED/MODIFIED/REMOVED、任务组格式、每组自带测试与质量门、关联场景清点维度、实施逻辑小节 |
+| `openspec/config.yaml` rules | **仅** schema 未覆盖的项目补充规则 | MODIFIED 终态契约表述、同语义一条需求、前置 change 标注格式、契约变更详列、访谈门与用户确认门、实施逻辑与方案摘要结构 |
 | 项目 `AGENTS.md` | 项目特化约束 | 技术栈、分层架构、数据库约定、质量门工具、方法论 |
 
 同一规则只写一处：config.yaml rules 不重复 schema instruction 已有内容；

package/assets/skills/openspec-standard/templates/schemas/spec-driven-standard/schema.yaml

@@ -108,16 +108,27 @@ artifacts:
         branches into the decisions that hang off it):
         * Problem & intent: what problem is being solved? what is the success criteria?
         * Scope: what is in/out of bounds? is the change decomposable into sub-changes?
-        * Related-surface survey (关联场景清点): enumerate every consumer of the
+        * Related-surface survey (关联场景清点): complete the survey BEFORE the
+          first interview round and treat it as input to the decision tree, not
+          just a documentation step. Enumerate every consumer of the
           capability being changed, grounded in real code — functional entry points
           (API endpoints, import/export entries, scheduled jobs, message consumers,
           frontend calls), shared processing logic reused by multiple entry points,
           and downstream data consumers (readers/writers of the tables, fields,
           events, or export artifacts involved). Record each finding with code
           evidence (file/class/method) in clarify.md's Related-Surface Survey
-          section. When shared processing logic changes, every consuming entry
-          point must be adapted within the SAME change; splitting into separate
-          changes requires an explicit boundary rationale confirmed by the user.
+          section. Every surveyed surface becomes a decision-tree branch that
+          MUST be resolved IN the interview: for each, ask the user whether it
+          is adapted in this change or excluded with a reason, and record the
+          verdict. Consistency branches are mandatory: when the same data has
+          multiple persistence paths (e.g. import, save, and update all writing
+          the same table), whether and how their validation and processing
+          logic stay shared and consistent must be asked and decided by the
+          user — touching only the requested path while skipping the related
+          paths means the interview is NOT exhausted. When shared processing
+          logic changes, every consuming entry point must be adapted within
+          the SAME change; splitting into separate changes requires an
+          explicit boundary rationale confirmed by the user.
         * Data model: which entities/tables/fields are involved? any new tables or columns?
         * Business rules: which are deterministic vs non-deterministic, per the
           project's conventions (see AGENTS.md)?
@@ -125,22 +136,50 @@ artifacts:
         * Architecture direction: propose 2-3 approaches with tradeoffs and a recommendation.
       - Round mechanics: each round asks every question whose prerequisites
         are already settled (the whole frontier at once) via the question
-        tool, numbered, each with your recommended answer; then wait for
-        the user's answers before the next round. A question whose answer
+        tool, numbered, each with your recommended answer; then wait for the
+        user's answers before the next round. A question whose answer
         depends on one still open in this round belongs to a later round.
         Facts are yours to find (codebase, specs, tools) - never ask the
         user for anything you can look up yourself; the decisions are the
         user's. Rounds continue until the frontier is empty: every branch
-        visited, no doubt left unresolved, nothing silently assumed.
+        visited, no doubt left unresolved, nothing silently assumed, and
+        every related-surface survey entry carries a user-confirmed scoping
+        verdict.
+      - Sequencing prohibition: while the interview is still open (the
+        frontier is not empty, or any related-surface survey entry lacks a
+        user-confirmed verdict), do NOT present the plan or a plan summary
+        and ask the user to confirm it. The recommended answer attached to
+        each question is not the plan and must never be presented as one;
+        do not fold plan confirmation into any interview round. If the user
+        asks for the plan mid-interview, say the interview is not finished
+        yet, you may recap what has already been settled, and keep asking
+        until the frontier is empty — only then use the plan confirmation
+        gate.
       - Challenge assumptions (yours and the user's). Reframe the problem when needed.
       - Plan confirmation gate (HARD-GATE): once the interview rounds have
-        exhausted every open doubt (frontier empty) and before starting
+        exhausted every open doubt (frontier empty — see the sequencing
+        prohibition above) and before starting
         Phase 2 (authoring — whether by you or
-        by a generation subagent), present a simple, direct plan summary to
-        the user and stop for confirmation. The summary must state: what the
-        change does in one sentence; whether it touches contracts (API
-        parameters or DDL); the chosen approach and its key trade-offs
-        versus the alternatives; the capabilities affected. Present it as a
+        by a generation subagent), present a direct plan summary to
+        the user and stop for confirmation. The summary MUST be structured:
+        number each element below and give it real substance — a
+        two-or-three-sentence blob is an invalid summary, expand it before
+        presenting. The elements:
+        1. what the change does, in one sentence;
+        2. whether it touches contracts (API parameters or DDL);
+        3. the chosen approach and its key trade-offs versus the
+           alternatives;
+        4. the implementation logic, step by step, in plain business
+           language (人话) — where the data comes from, what validation and
+           processing it goes through, where it lands, and how each related
+           path is adapted. Do NOT use code-level identifiers (class,
+           method, or internal function names) unless the user explicitly
+           asked for technical depth; contract facts (table, column, and
+           endpoint names) are exempt and stay precise;
+        5. the related-surface verdicts: for every surveyed surface,
+           adapted in this change or excluded, each with a one-line reason;
+        6. the capabilities affected.
+        Present it as a
         plain message — do NOT use the question tool for this confirmation
         (the question tool belongs to the interview rounds, not to this
         confirmation) — and stop for the user's free-text reply. Interview
@@ -157,12 +196,17 @@ artifacts:
       - **User Answers**: the user's responses, captured verbatim or summarized.
       - **Related-Surface Survey**: the related-surface survey output (关联场景清点) —
         every consuming entry point / shared processing logic / downstream
-        consumer with code evidence, and the scoping verdict for each. Shared
+        consumer with code evidence, and the scoping verdict for each —
+        every verdict confirmed by the user during the interview. Shared
         processing logic changes must be covered together with all their
         consuming entry points in the same change.
       - **Architecture Direction**: the crystallized approach, key decisions,
         alternatives considered, and the confirmed plan summary with
-        the user's explicit confirmation. This is the HARD-GATE output.
+        the user's explicit confirmation — the summary structured per the
+        six elements of the plan confirmation gate (including the
+        plain-language implementation outline and the related-surface
+        verdicts), presented as a plain message only after the interview
+        was exhausted. This is the HARD-GATE output.
       - **Initial Capabilities**: preliminary guess of which specs will be touched
         (kebab-case). Finalized in proposal.md.
 
@@ -196,11 +240,23 @@ artifacts:
       - **Related Surface (关联场景)**: the survey conclusions from clarify.md —
         every consuming entry point / shared processing logic / downstream
         consumer with code evidence and its scoping verdict (adapted in this
-        change, or explicitly justified out). When shared processing logic
+        change, or explicitly justified out). The verdicts recorded here must
+        match the user-confirmed verdicts from the clarify.md interview.
+        When shared processing logic
         changes, every consuming entry point must be adapted in THIS change;
         splitting into separate changes requires a boundary rationale section
         confirmed by the user. A bare "no related impact" without search
         evidence counts as an incomplete proposal.
+      - **Implementation Outline (实施逻辑)**: how the change plays out, step by
+        step, in plain business language (人话) — where the data comes from,
+        what validation and processing it goes through, where it lands, and
+        how each related path scoped into this change (per the Related
+        Surface section above) is adapted. What Changes lists WHAT changes;
+        this section walks through HOW it plays out, as numbered steps. Same
+        language rule as the plan summary: no code-level identifiers (class,
+        method, or internal function names) unless the user explicitly asked
+        for technical depth; contract facts (table, column, and endpoint
+        names) are exempt and stay precise.
       - **Capabilities**: Identify which specs will be created or modified:
         - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<capability-path>/spec.md`. Use kebab-case for path segments you introduce (e.g., `user-auth` or `identity/user-auth`) and follow the project's existing spec organization.
         - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Use the exact existing path under `openspec/specs/`. Leave empty if no requirement changes.
@@ -218,8 +274,10 @@ artifacts:
       behavior, so if behavior does not change, no spec should change either.
       Do not invent a requirement just to satisfy validation.
 
-      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
-      implementation details belong in design.md. Stay consistent with
+      Keep it concise (1-2 pages). The proposal covers the why and the
+      plain-language how (the Implementation Outline); code-level details
+      (class/method structure, DDL design, technology-choice argumentation)
+      belong in design.md. Stay consistent with
       clarify.md's architecture direction; if the proposal drifts from clarify,
       update clarify first and get user confirmation.
 

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

@@ -22,7 +22,10 @@
      import/export entries, scheduled jobs, message consumers, frontend calls),
      shared processing logic reused by multiple entry points, and downstream
      data consumers (readers/writers of the tables, fields, events, or export
-     artifacts involved). When shared processing logic changes, every consuming
+     artifacts involved). Every entry carries a scoping verdict (adapted in
+     this change, or excluded with a reason) confirmed by the user during the
+     interview — the frontier is not empty until every entry has one. When
+     shared processing logic changes, every consuming
      entry point must be adapted in the SAME change; splitting into separate
      changes requires an explicit boundary rationale confirmed by the user. -->
 
@@ -32,8 +35,13 @@
 
 <!-- The crystallized approach: chosen direction, key decisions, 2-3 alternatives
      considered with tradeoffs, and the plan summary the user explicitly confirmed
-     (interview answers alone do not count as confirmation; the summary must be a
-     plain message listing the key points — never a question-tool prompt). This is
+     (interview answers alone do not count as confirmation; the summary must be
+     structured per the six elements of the plan confirmation gate — including
+     the plain-language implementation outline and the related-surface verdicts —
+     presented as a plain message listing the key points, never a question-tool
+     prompt, and only AFTER the interview was exhausted: presenting the plan or
+     asking for its confirmation mid-interview is forbidden, and the recommended
+     answer attached to a question is not the plan). This is
      the HARD-GATE output — proposal, specs, design, and tasks must stay consistent
      with what is recorded here. -->
 

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

@@ -11,10 +11,20 @@
 <!-- 关联场景：survey conclusions from clarify.md — each entry point / shared
      processing logic / downstream consumer with code evidence and its scoping
      verdict (adapted in this change, or explicitly justified out with a boundary
-     rationale confirmed by the user). Shared processing logic changes must cover
-     all consuming entry points in this change. A bare "no related impact"
+     rationale confirmed by the user). Verdicts must match the user-confirmed
+     verdicts from the clarify.md interview. Shared processing logic changes must
+     cover all consuming entry points in this change. A bare "no related impact"
      without search evidence counts as an incomplete proposal. -->
 
+## Implementation Outline
+
+<!-- 实施逻辑：how the change plays out, step by step, in plain business
+     language (人话) — where the data comes from, what validation and processing
+     it goes through, where it lands, and how each related path scoped in above
+     is adapted. Numbered steps. No code-level identifiers (class/method/function
+     names) unless the user explicitly asked for technical depth; contract facts
+     (table/column/endpoint names) are exempt and stay precise. -->
+
 ## Capabilities
 
 ### New Capabilities

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.140.0",
+  "version": "0.142.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（漂移无害——文档、openspec 规划路径或仅版本号变更的 package.json——时直接合并收口；漂移含任一其他文件或文本冲突时回退到收尾验证 verify_cleanup 并返回 blocked），成功后销毁 worktree 并删分支。须在收尾验证（verify_cleanup）通过后调用。主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
     schema: completeTaskGroupSchema,
     execute: (args, ctx) => completeTaskGroupExecute(args as any, ctx),
   },

package/src/core/git.ts

@@ -172,13 +172,36 @@ export async function isAncestor(worktree: string, a: string, b: string): Promis
 /** 查询基准侧漂移文件清单：`git diff --name-only --no-renames <sourceBranch>...<targetBranch>`
  *  三点区间 = merge-base(source, target) 到 target 的内容差异（基准侧自分支切出点以来的净变化，非 commit 口径）。
  *  参数方向固定：source 传变更分支，target 传基准分支（切出点在 source 一侧）。
- *  返回 null 表示 git 查询失败，调用方须按非文档保守回退。 */
+ *  返回 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)
 }
 
+/**
+ * 判定单文件在三点区间（merge-base(source, target) → target）内的变更内容是否仅含 `"version"` 字段行：
+ * package.json 的版本号推进属发布元数据，无代码语义，收口漂移直通按无害漂移放行。
+ * 逐行解析 `git diff --no-renames <source>...<target> -- <filePath>` 的变更行（`+`/`-` 开头，跳过
+ * `+++`/`---` 文件头行）：每一行都须匹配 `"version"` 字段行才算 version-only；存在任一其他变更行
+ * （依赖、脚本等，具代码语义）→ false；无任何变更行（空 diff，内容无净变化）→ true。
+ * 返回 null 表示 git 查询失败，调用方须按非无害保守回退。
+ */
+export async function isVersionOnlyDrift(
+  worktree: string,
+  sourceBranch: string,
+  targetBranch: string,
+  filePath: string
+): Promise<boolean | null> {
+  const r = await runGitChecked(worktree, ["diff", "--no-renames", `${sourceBranch}...${targetBranch}`, "--", filePath])
+  if (!r.success) return null
+  for (const line of r.stdout.split("\n")) {
+    if (line.startsWith("+++") || line.startsWith("---")) continue
+    if ((line.startsWith("+") || line.startsWith("-")) && !/^[+-]\s*"version"\s*:/.test(line)) return false
+  }
+  return true
+}
+
 /** 校验本地分支存在（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, listBranchDriftFiles, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, removeTaskGroupWorktree, isLocalBranch, listLocalBranches, pathExists, type DetectChangesResult } from "../git.ts"
+import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isAncestor, isWorktreeClean, listBranchDriftFiles, isVersionOnlyDrift, 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,12 +1193,37 @@ function renderReviewIssueSummary(item: WorkItem): string {
   return lines.join("\n")
 }
 
-/** 漂移内容纯文档判定：null（查询失败）按非文档保守回退；空清单 = 内容无净变化（如基准上改了又回滚）视为纯文档；
- *  全部文件后缀属文档格式才放行。.txt 刻意排除（requirements.txt 等依赖清单具代码语义）。 */
+/** 漂移无害判定之文档后缀白名单：.txt 刻意排除（requirements.txt 等依赖清单具代码语义）。 */
 const DOCUMENTATION_EXTENSIONS = [".md", ".mdx", ".markdown", ".rst", ".adoc"]
-function isDocumentationOnly(files: string[] | null): boolean {
+/** 漂移无害判定之路径前缀白名单：openspec/ 为编排规划文档空间（提案/设计/任务/spec 等），不承载运行时代码。 */
+const DRIFT_NEUTRAL_PATH_PREFIXES = ["openspec/"]
+/**
+ * 漂移内容无害判定，满足其一即无害：文档后缀 / openspec 规划路径前缀 / package.json 且三点区间内容
+ * 仅含 `"version"` 字段行变化（版本号语义，无代码语义）。
+ * null（清单查询失败）按非无害保守回退；空清单 = 内容无净变化（如基准上改了又回滚）视为无害；
+ * version-only 内容查询失败（null）同样按非无害保守回退。
+ */
+async function isHarmlessDrift(
+  worktree: string,
+  sourceBranch: string,
+  targetBranch: string,
+  files: string[] | null
+): Promise<boolean> {
   if (files === null) return false
-  return files.every((f) => DOCUMENTATION_EXTENSIONS.some((ext) => f.endsWith(ext)))
+  const versionCandidates: string[] = []
+  for (const f of files) {
+    if (DOCUMENTATION_EXTENSIONS.some((ext) => f.endsWith(ext))) continue
+    if (DRIFT_NEUTRAL_PATH_PREFIXES.some((p) => f.startsWith(p))) continue
+    if (f === "package.json" || f.endsWith("/package.json")) {
+      versionCandidates.push(f)
+      continue
+    }
+    return false
+  }
+  for (const f of versionCandidates) {
+    if ((await isVersionOnlyDrift(worktree, sourceBranch, targetBranch, f)) !== true) return false
+  }
+  return true
 }
 
 /**
@@ -1330,17 +1355,18 @@ async function completeTaskGroupLocked(params: { change_id: string }, ctx: ToolC
 
   // 最后任务组 → change 级收口：合并 change 分支回基准分支（一次性），成功后销毁 worktree 并删分支
   const mergeTarget = state.baseBranch
-  // 纯文档漂移直通时的事实说明：仅在本次收口实际发生直通时非空；合并 blocked/conflict 分支不带该说明
+  // 无害漂移直通时的事实说明：仅在本次收口实际发生直通时非空；合并 blocked/conflict 分支不带该说明
   let docDriftNote = ""
   if (branchName) {
     // create-or-reuse（合并目标解析前）：在途旧模型会话升级时从当前基准 tip 创建，天然含已合入代码
     await ensureChangeBranch(ctx.worktree, branchName, mergeTarget)
 
     // 前置漂移检查（独立封装）：基准 tip 须为 change 分支祖先；不满足时先比对基准侧净变化内容——
-    // 纯文档漂移（含空清单 = 无净变化）不回退、直接合并收口；含任一非文档文件或清单查询失败 → 回退收尾验证并 blocked
+    // 无害漂移（文档 / openspec 规划路径 / 仅版本号变更的 package.json，含空清单 = 无净变化）不回退、
+    // 直接合并收口；含任一其他文件或清单/内容查询失败 → 回退收尾验证并 blocked
     if (!(await isAncestor(ctx.worktree, mergeTarget, branchName))) {
       const driftFiles = await listBranchDriftFiles(ctx.worktree, branchName, mergeTarget)
-      if (!isDocumentationOnly(driftFiles)) {
+      if (!(await isHarmlessDrift(ctx.worktree, branchName, mergeTarget, driftFiles))) {
         const workflow = loadWorkflowFile(resolveWorkflowPath(state))
         const rolledBack = rollbackToCleanupStep(item, workflow)
         if (rolledBack) await writeState(ctx.worktree, state)
@@ -1359,9 +1385,9 @@ async function completeTaskGroupLocked(params: { change_id: string }, ctx: ToolC
         ? `${files.slice(0, 10).join(", ")} 等 ${files.length} 个`
         : files.join(", ")
       docDriftNote =
-        `- **基准漂移（纯文档）**: 基准分支 \`${mergeTarget}\` 相对变更分支切出点净变化 ${files.length} 个文件` +
+        `- **基准漂移（无代码语义）**: 基准分支 \`${mergeTarget}\` 相对变更分支切出点净变化 ${files.length} 个文件` +
         (files.length > 0 ? `（${driftList}）` : "") +
-        "，均为文档，不影响代码语义，未回退收尾验证直接合并。"
+        "，均为文档、openspec 规划路径或仅版本号变更，不影响代码语义，未回退收尾验证直接合并。"
     }
 
     const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget)