@ifrankwang/openspec-agents 0.134.0 → 0.136.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);
         }
@@ -21715,6 +21716,45 @@ async function markTaskGroupCheckboxesComplete(worktree, changeId, taskGroupId)
     throw new Error(`git commit tasks.md 失败：${commitResult.stderr}`);
   }
 }
+function unquotePath(p) {
+  const t = p.trim();
+  return t.startsWith('"') && t.endsWith('"') && t.length >= 2 ? t.slice(1, -1) : t;
+}
+function parseStatusEntries(out) {
+  const entries = [];
+  for (const raw of out.split(`
+`)) {
+    if (raw.length < 4)
+      continue;
+    let line = raw;
+    if (line[2] !== " ") {
+      if (line[1] !== " ")
+        continue;
+      line = ` ${line}`;
+    }
+    if (line[0] === " " && line[1] === " ")
+      continue;
+    const pathPart = line.slice(3);
+    const arrow = pathPart.indexOf(" -> ");
+    const paths = arrow >= 0 ? [unquotePath(pathPart.slice(0, arrow)), unquotePath(pathPart.slice(arrow + 4))] : [unquotePath(pathPart)];
+    if (paths.every((p) => p !== ""))
+      entries.push({ x: line[0], y: line[1], paths });
+  }
+  return entries;
+}
+function parseDiffNameOnly(out) {
+  return out.split(`
+`).map(unquotePath).filter(Boolean);
+}
+function pathsOverlap(a, b) {
+  const na = a.replace(/\/+$/, "");
+  const nb = b.replace(/\/+$/, "");
+  if (!na || !nb)
+    return false;
+  if (na === nb)
+    return true;
+  return na.startsWith(`${nb}/`) || nb.startsWith(`${na}/`);
+}
 async function mergeBranchToTarget(repoDir, sourceBranch, targetBranch) {
   const mainRepo = await resolveMainRepoRoot(repoDir) ?? repoDir;
   const ancestor = await runGitChecked(mainRepo, ["merge-base", "--is-ancestor", sourceBranch, targetBranch]);
@@ -21733,18 +21773,6 @@ async function mergeBranchToTarget(repoDir, sourceBranch, targetBranch) {
           `- **原因**: 目标分支 \`${targetBranch}\` 正被工作树 \`${checkedOutPath}\` 检出；自动推进分支指针会使该工作树的暂存区/工作区与分支引用失步，本次未执行任何合并动作。`,
           `- **处理**: 请在该工作树手动执行 \`git merge ${sourceBranch}\`，或移除该工作树（\`git worktree remove ${checkedOutPath}\`）后重试。`
         ].join(`
-`)
-      };
-    }
-    const status = await runGit(mainRepo, ["status", "--porcelain"]);
-    if (status.trim().length > 0) {
-      return {
-        success: false,
-        conflict: false,
-        blockedMessage: [
-          `- **原因**: 目标分支 \`${targetBranch}\` 正被主仓库检出，且主仓库存在未提交改动；为避免覆盖本地改动，本次未执行任何合并动作（分支引用未动、无半成品）。`,
-          `- **处理**: 请先 commit 或 stash 主仓库改动后重试；或自行执行 \`git merge ${sourceBranch}\`（真实合并自带脏工作区保护）。`
-        ].join(`
 `)
       };
     }
@@ -21755,6 +21783,65 @@ async function mergeBranchToTarget(repoDir, sourceBranch, targetBranch) {
       }
       return { success: false, conflict: true };
     }
+    const mergedTreeOid = mergeTree.stdout.split(`
+`)[0].trim();
+    const statusRes = await runGitChecked(mainRepo, ["status", "--porcelain"]);
+    if (!statusRes.success) {
+      throw new Error(`无法读取主仓库工作区状态：${statusRes.stderr}`);
+    }
+    const entries = parseStatusEntries(statusRes.stdout);
+    if (entries.length > 0) {
+      const dirtyPaths = [...new Set(entries.flatMap((e) => e.paths))];
+      const written = parseDiffNameOnly(await runGit(mainRepo, ["diff", "--name-only", "--no-renames", targetBranch, mergedTreeOid]));
+      const overlap = written.filter((w) => dirtyPaths.some((d) => pathsOverlap(d, w)));
+      if (overlap.length > 0) {
+        return {
+          success: false,
+          conflict: false,
+          blockedMessage: [
+            `- **原因**: 目标分支 \`${targetBranch}\` 正被主仓库检出，且以下本地改动文件与任务组合并将写入的文件重合；为避免覆盖本地改动，本次未执行任何合并动作（分支引用未动、无半成品）：`,
+            ...overlap.map((f) => `  - \`${f}\``),
+            `- **处理**: 请先 commit/stash/移除上述文件的本地改动后重试；或自行执行 \`git merge ${sourceBranch}\`（真实合并自带脏工作区保护）。`
+          ].join(`
+`)
+        };
+      }
+      const stagedPaths = [...new Set(entries.filter((e) => e.x !== " " && e.x !== "?").flatMap((e) => e.paths))];
+      if (stagedPaths.length > 0) {
+        const unstagedDelta = await runGit(mainRepo, ["diff", "--name-only", "--", ...stagedPaths]);
+        if (parseDiffNameOnly(unstagedDelta).length > 0) {
+          return {
+            success: false,
+            conflict: false,
+            blockedMessage: [
+              `- **原因**: 主仓库存在部分暂存文件（同一文件既有已暂存又有未暂存改动），自动合并会改变暂存粒度；本次未执行任何合并动作（分支引用未动、无半成品）。`,
+              `- **处理**: 请先 commit 或 stash，或补全/取消暂存后重试；或自行执行 \`git merge ${sourceBranch}\`。`
+            ].join(`
+`)
+          };
+        }
+        let unstagedByUs = false;
+        try {
+          const restore = await runGitChecked(mainRepo, ["restore", "--staged", "--", ...stagedPaths]);
+          if (!restore.success)
+            throw new Error(`git restore --staged 失败（未执行合并）：${restore.stderr}`);
+          unstagedByUs = true;
+          const mergeResult = await runGitChecked(mainRepo, ["merge", "--no-ff", sourceBranch]);
+          if (!mergeResult.success) {
+            await runGitChecked(mainRepo, ["merge", "--abort"]);
+            return { success: false, conflict: true };
+          }
+          return { success: true, conflict: false };
+        } finally {
+          if (unstagedByUs) {
+            const readd = await runGitChecked(mainRepo, ["add", "--", ...stagedPaths]);
+            if (!readd.success) {
+              throw new Error(`合并后还原暂存态失败（git add）：${readd.stderr}；请人工核对这些文件的暂存状态`);
+            }
+          }
+        }
+      }
+    }
     const mergeResult = await runGitChecked(mainRepo, ["merge", "--no-ff", sourceBranch]);
     if (!mergeResult.success) {
       await runGitChecked(mainRepo, ["merge", "--abort"]);
@@ -30075,7 +30162,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: "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突、主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
     schema: completeTaskGroupSchema,
     execute: (args, ctx) => completeTaskGroupExecute(args, ctx)
   },
@@ -30120,7 +30207,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.134.0";
+var PKG_VERSION = "0.136.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

@@ -11,6 +11,7 @@
 
 - **多工具支持**：Claude Code、Codex、ZCode、DeepSeek Harness（DSH）、OpenCode 均可原生接入。
 - **规范驱动**：直接消费 OpenSpec 变更规范（proposal / design / tasks / specs），流程与规范一一对应。
+- **提案标准化**：内置 OpenSpec 提案标准（关联场景清点、契约变更详列、动笔前访谈与用户确认），一键初始化到任意项目，在提 change 阶段防漏考虑、防拆分割裂。
 - **智能体团队**：不再是单个 AI 从头写到尾，而是「实现者 + 审查者 + 质量把关者」分工协作，结果更稳。
 - **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。任务验证层（任务审查 / 合并审查）以通过（passed）提交时必须逐项确认全部已申报任务（verified_tasks 全覆盖为工具强制门禁）；已通过但漏带确认导致阻塞时，审查者可补交确认结果解除阻塞。simple 模式下验证按性质分流——开发者执行确定性检查并申报，审查者分级复验（低成本项实跑、高成本项核验申报加抽样重放）并专注对抗性判断。
 - **隔离执行**：每个变更在独立的环境中实施，互不干扰；变更完成后合并并清理。
@@ -72,6 +73,20 @@ npm install -D @ifrankwang/openspec-agents
 
 如果已经安装，只需说一句「请运行 openspec-agents 编排流程」即可开工。AI 会负责完成安装、初始化、任务分派与质量把关的全部步骤。
 
+## 标准化提 change（提案标准初始化）
+
+插件内置一套 OpenSpec 提案标准，在「提 change」阶段就把好质量关：
+
+- **关联场景清点**：动笔前以代码检索为证据，枚举变更触及能力的全部消费方（功能入口、共享处理逻辑、数据流下游）；共享处理逻辑变更时全部消费入口必须同一 change 统一适配，防止同一逻辑两边割裂维护。
+- **契约变更详列 / 动笔前访谈门 / 用户确认门**：DDL 与接口契约逐条列明；决策树访谈穷尽疑点；方案摘要经用户确认后才动笔。
+- **任务组实质变更主体**：任务组以真实代码变更为主体，禁止收尾验证组与人工门禁任务。
+
+在装了插件的工具里，于目标项目的**常规主代理会话**（非编排流程中的主代理——编排人格禁止修改文件，无法执行初始化）说一句：
+
+> 初始化 openspec 提案标准
+
+即可把标准写入该项目（`openspec/config.yaml` + `openspec/schemas/spec-driven-standard/`），此后该项目用 openspec 提 change 自动遵循标准。已初始化的项目重跑即升级到最新标准，项目自定义 rules 条目与 context 保留；标准方法论自包含，不依赖任何外部 skill。
+
 ## 工作原理（简述）
 
 1. **输入**：项目中的 OpenSpec 变更规范（变更说明、设计、任务清单、验收规格）。

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

@@ -0,0 +1,28 @@
+---
+name: openspec-standard
+description: OpenSpec 提案标准初始化与升级——把标准版提案规则（openspec/config.yaml + spec-driven-standard schema 全套）安装到当前项目，统一后续提 change 的质量门槛（关联场景清点、契约变更详列、动笔前访谈与用户确认）。当用户要求初始化、升级或标准化 openspec 提案标准/提案规范时使用。
+capabilities: ["openspec-standard"]
+---
+
+## 职责
+
+把本 skill 目录 `templates/` 下的标准文件安装到当前项目的 `openspec/` 目录，使该项目此后用 openspec 提 change 时自动遵循统一标准：关联场景清点（共享处理逻辑的变更须与其全部消费入口同一 change 统一适配）、契约变更详列、动笔前访谈门与用户确认门、任务组实质变更主体等。幂等：重跑即把标准升级到插件当前版本，项目自定义内容按下方合并策略保留。
+
+## 前置检查
+
+- 当前项目根不存在 `openspec/` 目录 → 该项目尚未初始化 OpenSpec。提示用户先完成 openspec 初始化（建立 `openspec/` 目录与基础配置）后再执行本 skill，终止。
+
+## 安装/升级流程
+
+1. 读取本 skill 目录 `templates/` 下全部文件。
+2. `openspec/config.yaml`：
+   - 项目尚无该文件 → 直接写入模板内容；
+   - 已存在 → 合并升级：`schema:` 一律改为 `spec-driven-standard`；`context:` 保留项目已有内容（无则用模板内容）；`rules.*` / `operations.*` 各小节中，与标准条目同源的条目替换为模板最新文本，项目自定义条目（模板中不存在的）原样保留并追加在同小节标准条目之后。
+3. `openspec/schemas/spec-driven-standard/`：整目录写入（schema.yaml、README.md、`templates/` 下五个文档模板）；该目录为标准自有内容，已存在时直接覆盖。
+4. 项目既有其它 schema 目录一律不动（既有 change 的 `.openspec.yaml` 可能引用）；在汇报中说明：确认没有 change 再引用旧 schema 后，可手动删除旧目录。
+5. 汇报：本次新建/更新/保留的文件与 config.yaml 条目清单；如项目此前使用其它 schema，说明此后新 change 将使用 spec-driven-standard。
+
+## 约束
+
+- 只允许写 `openspec/config.yaml` 与 `openspec/schemas/spec-driven-standard/` 下的文件，不修改项目其它任何文件。
+- 标准文本原样落盘，不自行改写；项目特化约束（技术栈、分层架构、质量门工具等）属于项目 AGENTS.md，不在本 skill 范围。

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

@@ -0,0 +1,39 @@
+schema: spec-driven-standard
+
+context: |
+  项目技术背景、架构约定与工程规范以项目根目录 AGENTS.md 为准。
+  本文件仅承载 OpenSpec 流程的通用规则；与项目相关的特化约束
+  （技术栈、分层架构、数据库约定、质量门、方法论选择等）一律写入
+  项目 AGENTS.md，生成与复核子代理会被指示读取它。
+  explore 模式与 proposal 侧同源同严：凡涉及理清需求，必须按
+  spec-driven-standard schema clarify 指令的决策树访谈方法论逐轮穷尽
+  疑点；疑点未穷尽不得收束结论、不得捕获任何变更工件
+  （proposal/specs/design/tasks），不得以「需求简单」等理由跳过。
+
+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 任一文档动笔前，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 内容。"
+    - "同一语义只保留一条需求：修改已有需求用 MODIFIED，不得以新标题重复描述同一能力。"
+  tasks:
+    - "每个任务组必须以实质变更为主体（强制）：组内至少一个任务承载真实的代码/配置行为变更（实现 + 测试）；文档/脚本/部署文档同步、验证、回归、质量门只是随行工作，不构成组的实质内容。任务条数不等于实质——排到末位的剩余工作若只剩同步与验证，必须并入前一个功能组，禁止为其新开组（反例：「阶段二收尾：文档、脚本与全量验证」式收尾组）。"
+    - "任务组覆盖关联入口（强制）：tasks.md 的任务组划分必须覆盖 proposal.md「关联场景」小节划入本 change 的全部消费入口；任一划入入口缺少对应适配任务视为 tasks 未完成。"
+    - "真跨组依赖应拆为独立前置 change，在组标题下用 `> **前置 change：**` 标注，组间不可并行。"
+    - "禁止人工门禁任务：不得生成\"等待用户确认/人工验收/人工回归后再继续\"式的任务或检查点；验证一律以自动化手段（编译、测试、质量门）闭环，确需人工执行的回归留档于 design.md 的 Risks/Migration，不进入 tasks.md。"
+    - "禁止真实调用生产接口的任务：联调与验证只允许本地/测试环境（容器化测试、桩/mock 服务、本地 profile 的 API 测试），生产环境接口调用不得作为任务出现。"
+
+operations:
+  archive:
+    guidance:
+      - "归档前必须完成变更同步：delta 与主 spec 有差异时禁止直接归档。"
+      - "归档同步无条件执行，无需用户确认：delta 与主 spec 存在差异时直接同步后归档，禁止提供\"不同步归档\"选项或就此询问用户；仅当同步失败或一致性校验无法收敛时停止并向用户报告。"
+      - "主 spec 只描述当前契约：应用 MODIFIED 时把\"原 X 改为 Y\"式描述改写为终态表述，已废弃组件（表/类/接口/端点）不得保留在主 spec。"
+      - "delta 出现移除/废弃/不再语义时，必须在主 spec 删除对应需求或场景，并在 delta spec 补写 `## REMOVED Requirements` 保持可追溯。"
+      - "同一语义只保留一条需求：与已有需求重叠时合并，不得新增重复标题。"
+      - "同步收敛：同步完成后主 spec 须完整反映 delta——ADDED 已存在、MODIFIED 为终态、REMOVED 已消失。"
+      - "归档前运行 `openspec validate` 校验 MODIFIED 与主 spec 一致性，并核对主 spec 无变更式表述残留、无 REMOVED 残留、无重复需求、无空 spec 目录、无残留 TBD；未通过先修复。"

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

@@ -0,0 +1,79 @@
+# OpenSpec Schema: spec-driven-standard
+
+通用 spec-driven 工作流模板：clarify → proposal → specs → design → tasks，
+增强三点：
+1. **clarify 前置门槛 + 关联场景清点**：每次变更先做需求澄清与关联场景清点
+   （枚举变更触及能力的全部消费方——功能入口 / 共享处理逻辑 / 数据流下游，
+   附代码证据；共享处理逻辑变更须与其全部消费入口同一 change 统一适配）；
+   访谈结束后、写任何文档之前，主代理必须先向用户简单直接汇报方案（一句话
+   讲清做什么 + 是否动契约 + 取舍 + 影响面）并取得用户明确确认（HARD-GATE：
+   汇报须以普通消息直接列出要素点，禁止用提问工具发起确认，访谈中的问答
+   不视为确认），确认记录落在 clarify.md，后续文档不得偏离。
+2. **主代理访谈直录 + 分级撰写 + 独立复核循环**：主代理亲自访谈，问答
+   直接记入 clarify.md（访谈阶段唯一落笔的文档，不设独立访谈文件）；
+   架构方向经用户确认后，按复杂度分级产出其余文档（proposal → specs →
+   design → tasks，不逐文档分派）——简单变更由主代理本人按依赖顺序撰写
+   （省 token），复杂变更派发唯一一个独立生成子代理在同一会话内撰写（保
+   主代理上下文精简），分级判定与理由记入 clarify.md；无论哪级，主代理
+   必须派发独立复核子代理全量检查（结构校验 + 规则核对 + 与主 spec 交叉
+   核对），发现问题由主代理本人修复后再次复核，循环最多 3 轮，复核干净
+   通过（PASS）才算完成。完整三阶段编排契约写在 clarify 的 instruction
+   里——这是主代理必读的一份，复核派发由此可达；复杂变更的生成子代理
+   最终汇报必须提示主代理进入复核阶段，双保险防契约断链。
+3. **自包含方法论**：决策树逐轮访谈（frontier 机制）全文内联在 clarify
+   instruction 的 Methodology 节，不依赖任何外部 skill。
+
+## 目录
+
+```
+openspec/schemas/<schema-name>/
+├── schema.yaml    # 流程与文档结构定义（纯通用，无项目内容）
+├── templates/     # 各文档模板（纯通用）
+└── README.md      # 本说明
+```
+
+配套文件（一并安装）：项目根 `openspec/config.yaml`（通用流程规则）。
+
+## 接入新项目
+
+**方式一（推荐，插件一键初始化）**：安装了 openspec-agents 插件的 AI 编码
+工具中，在目标项目的常规主代理会话里说一句「初始化 openspec 提案标准」，
+即自动写入本 schema 目录与配套 `openspec/config.yaml`；已初始化的项目重跑
+即升级到最新标准（项目自定义 rules 条目与 context 保留）。
+
+**方式二（手动回退，无插件环境）**：
+1. 把本目录整体 copy 到新项目 `openspec/schemas/spec-driven-standard/`。
+2. 把通用版 `openspec/config.yaml` copy 到新项目，确认 `schema:` 指向
+   `spec-driven-standard`。
+3. 在新项目 `AGENTS.md` 中写清项目特化约束（见下节），并确认每次变更的
+   `.openspec.yaml` 的 `schema:` 字段指向正确。
+
+> 生成子代理（复杂变更时）与复核子代理会被指示读取项目 `AGENTS.md` 与
+> `openspec/config.yaml`，因此项目特化约束写在 `AGENTS.md` 即可自动生效，
+> schema 本身无需改动。
+
+## 项目特化约束清单（写进 AGENTS.md 的内容）
+
+| 类别 | 示例 |
+|---|---|
+| 技术栈 | 语言/框架/版本、构建工具、依赖管理 |
+| 分层架构 | 分层/包组织、依赖方向、层间规则 |
+| 领域约定 | 确定性 vs 不确定性分工、领域模型规范 |
+| 数据库约定 | 表前缀、主键策略、审计字段、逻辑删除、迁移方式 |
+| 质量门 | 格式/静态检查工具、测试策略、覆盖率门槛 |
+| 方法论 | 澄清/评审/开发流程约定（如 TDD） |
+
+## 三层分工（不重复原则）
+
+| 位置 | 承载内容 | 例子 |
+|---|---|---|
+| `schema.yaml` instruction | 生成方法论与文档格式要求（官方方法论为底） | 场景标题 4 个 #、SHALL/MUST、ADDED/MODIFIED/REMOVED、任务组格式、每组自带测试与质量门、关联场景清点维度 |
+| `openspec/config.yaml` rules | **仅** schema 未覆盖的项目补充规则 | MODIFIED 终态契约表述、同语义一条需求、前置 change 标注格式、契约变更详列、访谈门与用户确认门 |
+| 项目 `AGENTS.md` | 项目特化约束 | 技术栈、分层架构、数据库约定、质量门工具、方法论 |
+
+同一规则只写一处：config.yaml rules 不重复 schema instruction 已有内容；
+schema 不写项目专属内容。新增规则时先查上一层的 instruction 是否已覆盖。
+
+官方升级 `openspec update` 会覆盖 `.agents/skills/` 下的 skill，本 schema
+与 config.yaml 不受影响；CLI 升级后可重新对齐官方 `spec-driven`
+（`openspec schema fork`）再叠加本模板的增强段落。

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

@@ -0,0 +1,469 @@
+name: spec-driven-standard
+version: 1
+description: Spec-driven workflow with clarify gate, related-surface survey, tiered authoring (orchestrator or single subagent) and review loop - clarify → proposal → specs → design → tasks
+artifacts:
+  - id: clarify
+    generates: clarify.md
+    description: Requirement and architecture clarification record
+    template: clarify.md
+    instruction: |
+      **Orchestration contract (addressed to YOU, the orchestrating agent)**:
+      Duties are split into three phases. You personally run Phase 1 and
+      Phase 3. Phase 2 is TIERED by change complexity: for SIMPLE changes
+      you write proposal/specs/design/tasks yourself; for COMPLEX changes a
+      single fresh generation subagent writes them. No subagent ever writes
+      clarify.md - you write it yourself as the interview record.
+
+      Phase 1 - Interview (you): investigate the codebase and existing
+      openspec/specs/ first, then interview the user in rounds over a
+      decision tree using the frontier mechanics (methodology below),
+      recording questions and answers directly into <changeRoot>/clarify.md
+      as you go (sections below) - there is no separate interview file.
+      HARD-GATE: the interview is over only when every branch of the decision
+      tree has been visited, no doubt is left open, nothing is silently
+      assumed; then first present a simple, direct plan summary to the user
+      and get an explicit confirmation of the direction - do NOT start
+      Phase 2 (authoring) until the user has confirmed it (details in
+      methodology below).
+
+      Phase 2 - Authoring (TIERED): only after the user has explicitly
+      confirmed the plan summary (HARD-GATE above), decide the tier using
+      the complexity criteria below, record the decision and one-line
+      rationale in clarify.md, then
+      follow the matching mode:
+      - SIMPLE tier: you personally produce the remaining artifacts
+        (proposal → specs → design → tasks) in dependency order. For each
+        artifact run `openspec instructions <artifact-id> --change
+        "<name>" --json` yourself, read the project's AGENTS.md and
+        openspec/config.yaml rules plus the dependency artifacts (starting
+        from the clarify.md you wrote), and write to the resolved output
+        path. Do not dispatch any subagent for authoring.
+      - COMPLEX tier: dispatch a single fresh general-purpose subagent
+        with the change name. It produces the remaining artifacts in one
+        session: for each it runs
+        `openspec instructions <artifact-id> --change "<name>" --json`
+        itself, reads the project's AGENTS.md and openspec/config.yaml
+        rules plus the dependency artifacts, and writes to the resolved
+        output path. It may only read/write inside the change directory
+        (openspec/changes/<name>/). It must not dispatch further
+        subagents, and its final report MUST end by telling you to start
+        Phase 3.
+
+      Complexity criteria - COMPLEX if ANY applies, otherwise SIMPLE:
+      - touches 2+ capabilities or 2+ task groups with cross-group
+        dependencies;
+      - significant data-model change (new tables, many columns, or any
+        data migration);
+      - new external dependency, new architectural pattern, or notable
+        security/performance/migration complexity;
+      - expected total artifact size would push your context near the
+        window limit if you wrote them yourself (large DDL, long task
+        lists, multi-spec changes).
+      When in doubt, choose COMPLEX: it keeps the orchestrating agent's
+      context lean and is the safer default.
+
+      Phase 3 - Review loop (you, once authoring is complete):
+      1. Dispatch an independent review subagent (fresh general-purpose
+         session — never reuse the generation subagent). It must:
+         - run `openspec validate "<name>" --strict` for structural checks
+           (note: validate takes the change name as a positional argument,
+           no --change flag);
+         - check every artifact against the openspec/config.yaml rules for
+           its stage, the schema templates/instructions, and cross-document
+           consistency (clarify direction ↔ proposal capabilities ↔ specs
+           requirements ↔ design decisions ↔ tasks with [spec:...]
+           traceability tags);
+         - read openspec/specs/ main specs (read-only) and cross-check:
+           proposal capabilities actually exist there, and delta
+           requirements/contracts (e.g. error codes, rate-limit semantics,
+           existing implementations) do not conflict with what the main
+           specs already establish;
+         - write findings to <changeRoot>/.review/issues.md, one block per
+           issue with fields: severity | file | problem | suggested fix;
+           write "PASS" when clean. The .review/ directory exists only for
+           this working file during the loop - never use it to record
+           anything else.
+      2. If issues.md is not "PASS", YOU fix every issue yourself
+         (change-directory documents only; you must not modify issues.md
+         itself, and you must not delegate fixes to a subagent — fixing
+         in your own context is the token-saving design).
+      3. Re-dispatch the review subagent for a fresh full review; loop
+         until "PASS" or 3 review rounds. After 3 rounds with remaining
+         issues, stop and present the leftover issues to the user.
+      4. On "PASS", delete the .review/ directory.
+
+      Do NOT hand over to the apply workflow before Phase 3 ends with
+      "PASS" (or with leftover issues explicitly accepted by the user).
+
+      Create the clarify document that records the requirement clarification and
+      architecture direction exploration BEFORE any proposal is written. This
+      artifact is MANDATORY for every change - it captures the think-before-build
+      phase, grounded in the actual codebase and existing specs.
+
+      Methodology:
+      - Investigate the codebase and existing openspec/specs/ first. Ground every
+        question in real code; do not theorize without reading the relevant modules.
+      - Surface unknowns across these dimensions and resolve them with the
+        user by interviewing in rounds over a decision tree (every decision
+        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
+          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.
+        * 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)?
+        * Integration boundaries: external systems, APIs, ports/adapters?
+        * 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
+        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.
+      - 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
+        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
+        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
+        answers do NOT count as confirmation — the confirmation must be a
+        direct user response to this summary. If the user requests changes,
+        revise the summary and re-present; loop until the user explicitly
+        confirms. Record the confirmed summary in clarify.md's Architecture
+        Direction section. "Too simple to need clarification" is not a
+        valid reason to skip; the clarify record may be short but must
+        exist, and this confirmation step is still mandatory.
+
+      Sections (see template):
+      - **Open Questions**: the unknowns surfaced, one per bullet.
+      - **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
+        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.
+      - **Initial Capabilities**: preliminary guess of which specs will be touched
+        (kebab-case). Finalized in proposal.md.
+
+      This is the foundation for proposal, specs, design, and tasks. All later
+      artifacts must stay consistent with the direction recorded here.
+    requires: []
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create the proposal document that establishes WHY this change is needed.
+
+      Sections:
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+      - **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
+        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.
+      - **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.
+      - **Impact**: Affected code, APIs, dependencies, or systems.
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract between
+      proposal and specs phases. Research existing specs before filling this in.
+      Each capability listed here will need a corresponding spec file.
+
+      Every change must either declare at least one capability (new or
+      modified) or explicitly opt out of specs: `openspec validate` rejects a
+      change with zero deltas unless the change's `.openspec.yaml` sets
+      `skip_specs: true`. Use `skip_specs: true` only when no spec-level
+      behavior changes (pure refactor, tooling, docs) - specs describe
+      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
+      clarify.md's architecture direction; if the proposal drifts from clarify,
+      update clarify first and get user confirmation.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    requires:
+      - clarify
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create specification files that define WHAT the system should do.
+
+      A spec is a behavior contract, not an implementation plan.
+
+      Good spec content:
+      - Observable behavior users or downstream systems rely on
+      - Inputs, outputs, and error conditions
+      - External constraints (security, privacy, reliability, compatibility)
+      - Scenarios that can be tested or explicitly validated
+
+      Avoid in specs:
+      - Internal class/function names
+      - Library or framework choices
+      - Step-by-step implementation details
+      - Detailed execution plans (those belong in design.md or tasks.md)
+
+      Quick test: if the implementation can change without changing externally
+      visible behavior, it likely does not belong in the spec.
+
+      Create one spec file per capability listed in the proposal's Capabilities section.
+      `<capability-path>` is the spec directory relative to `specs/` (for example,
+      `user-auth` or `identity/user-auth`). Preserve the full path:
+      - New capabilities: use the exact path from the proposal at `specs/<capability-path>/spec.md`. Any path segment newly introduced in the proposal must be kebab-case. Follow the project's existing organization; do not add a new domain level when the project uses a flat layout.
+      - Modified capabilities: use the exact existing path from `openspec/specs/<capability-path>/` when creating the delta at `specs/<capability-path>/spec.md`. Do not move or rename the capability.
+
+      There must be at least one spec file unless the change's `.openspec.yaml`
+      sets `skip_specs: true` (no spec-level behavior change) - `openspec validate`
+      rejects a zero-delta change without that marker. If the proposal lists no
+      capabilities and `skip_specs` is not set, revisit the proposal first.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+
+      New capabilities only: start the delta spec with a `## Purpose` section -
+      one or two sentences (50+ characters, or `openspec validate --strict`
+      reports it as too brief) describing what the capability is for. Archive
+      copies it into the main spec it creates; without it the new main spec is
+      left with a `TBD ... Update Purpose after archive` placeholder to fill in
+      by hand. Do NOT add `## Purpose` to a delta for an existing capability -
+      that spec already has one and the delta's is ignored. To change an
+      existing capability's Purpose - including a leftover `TBD` placeholder -
+      edit `openspec/specs/<capability-path>/spec.md` directly.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in openspec/specs/<capability-path>/spec.md
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+      If adding new concerns without changing existing behavior, use ADDED instead.
+
+      Specs should be testable - each scenario is a potential test case.
+    requires:
+      - proposal
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create the design document that explains HOW to implement the change.
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Only the current state and constraints needed to explain the approach. Reference the proposal for motivation instead of restating it (e.g., "See proposal.md - Why").
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes. Don't restate the proposal's scope - add only design-level boundaries.
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Data Model**: MANDATORY when the change involves persistence. Complete
+        DDL (CREATE TABLE with columns, types, constraints), field descriptions,
+        indexes, and audit fields. Follow the project's persistence conventions
+        (see AGENTS.md / openspec/config.yaml rules). If the change does not
+        involve persistence, state that explicitly ("本变更不涉及持久化" or the
+        project's equivalent phrasing).
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Unknowns that can safely be answered later without
+        changing the specs, the approach, or the task breakdown. Omit if none.
+
+      Open questions are for genuinely deferrable unknowns, not decisions you
+      skipped. If a question would change the specs, the chosen approach, or
+      the task breakdown, resolve it now - ask the user instead of guessing.
+
+      Focus on architecture and approach, not line-by-line implementation.
+      The proposal covers why and what; design covers how. Reference the
+      proposal for motivation and, once written, the specs for requirements -
+      if a section would only restate them, point to them instead.
+
+      Good design docs explain the "why" behind technical decisions.
+    requires:
+      - proposal
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      **Generation (process constraint)**: This artifact is written by exactly
+      one author — either YOU, the orchestrating agent (SIMPLE tier), or the
+      ONE independent generation subagent dispatched once for the change
+      (COMPLEX tier) — never one subagent per artifact, and never by both.
+      The full orchestration contract (interview, tier decision, authoring,
+      review loop) lives in the clarify artifact's instruction; read it
+      first if you have not. The author runs
+      `openspec instructions <artifact-id> --change "<name>" --json`, reads
+      the project's AGENTS.md and openspec/config.yaml rules plus the
+      dependency artifacts (including the clarify.md written by the
+      orchestrating agent), then writes to the resolved output path. If a
+      generation subagent is the author, it may only read/write inside the
+      change directory (openspec/changes/<name>/).
+
+      Create the task list that breaks down the implementation work.
+
+      Before writing tasks, check design.md for Open Questions. If any of them
+      would change what gets built, resolve them with the user first - do not
+      bake an unstated assumption into the task list.
+
+      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+
+      Guidelines:
+      - Group related tasks under `## N. <Task Group Name>` numbered headings
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Each task SHOULD end with a traceability tag `[spec:<capability>#<requirement>]`
+        (or `[infra]` for pure cross-cutting infrastructure tasks). Business tasks
+        without a spec target are out of scope - remove them or add the spec
+        requirement first.
+      - **Related-surface coverage (关联场景覆盖)**: the task groups must cover
+        every consuming entry point that the proposal's Related Surface section
+        scopes into this change; an in-scope entry point without an adaptation
+        task counts as an incomplete task list.
+      - **Each task group = one independent iteration.** Every group MUST contain:
+        implementation + tests + a quality gate (the project's quality gate per
+        openspec/config.yaml rules / AGENTS.md). No standalone QA group - quality
+        is embedded in every iteration. Groups must be independently implementable:
+        when a group is done, the code compiles and tests pass.
+      - **No verification group, pure or mixed.** Pure verification work —
+        quality-gate runs (e.g. a final full build verification), end-to-end / integration /
+        regression / smoke verification, residual-search sweeps (旧键残留检索),
+        regression confirmation — must never form a task group of its own:
+        neither standalone, nor as a "wrap-up" group that mixes them with
+        doc/script/config sync tasks (e.g. 「阶段二收尾：文档、脚本与全量验证」).
+        Fold verification tasks into the functional group they verify. Doc/script/
+        config sync tasks are functional work and join the functional group they
+        accompany — their presence does not legitimize a wrap-up group. Group
+        titles name the delivered business value; 收尾/验证/回归 must never be a
+        group's identity.
+      - **Minimum substance per group.** Every group's body must be substantive
+        change content: at least one task that changes behavior-bearing code or
+        config (implementation + its tests). Doc/script/deploy-doc sync,
+        verification, regression and quality-gate tasks are accompaniment —
+        they may join a functional group but never constitute its substance,
+        and task count does not substitute for substance (a 6-task group of
+        only sync + verification work still violates this rule). The last
+        group of a change is the typical decay spot: when the work remaining
+        for a would-be group is only sync + verification, fold it into the
+        preceding functional group instead of opening a tail group.
+      - Grouping priority (in order):
+        1. **Implementation order**: groups follow the project's layer dependency
+           order (see AGENTS.md / config.yaml rules). Earlier groups define
+           interfaces/models that later groups consume.
+        2. **Coherent scope**: each group delivers a complete, verifiable business
+           value — a feature, a sub-feature, or a set of closely related capabilities.
+        3. **Group size balance**: aim for 4-8 tasks per group. Groups with < 4
+           tasks → merge into an adjacent group. Groups with > 8 tasks → split
+           into focused sub-groups (each with its own tests and quality gate).
+      - Task ordering within a group: dependency chain — define → implement →
+        test → quality gate.
+      - Tasks should be small enough to complete in one session (~5-10 min coding).
+        Implementation details exceeding 10 lines belong in actual code, not as
+        separate sub-tasks.
+
+      Reference specs for what needs to be built, design for how to build it.
+      Each task should be verifiable - you know when it's done.
+
+      **Final report (process constraint)**: When this artifact is written,
+      every artifact of the change exists and the authoring session ends
+      here. You must NOT dispatch any subagent yourself. If you are the
+      generation subagent (COMPLEX tier), your final report MUST end by
+      telling the orchestrating agent to start the review loop (Phase 3 of
+      the clarify artifact's orchestration contract) - without that handoff
+      the review never happens. If you are the orchestrating agent (SIMPLE
+      tier), go straight to Phase 3 yourself and dispatch the independent
+      review subagent.
+    requires:
+      - specs
+      - design
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Follow the project's implementation conventions (AGENTS.md, openspec/config.yaml
+    rules, and any orchestration workflow the project uses).
+    Pause if you hit blockers or need clarification.

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

@@ -0,0 +1,55 @@
+## Open Questions
+
+<!-- Unknowns surfaced during clarification. One per bullet. Cover: problem & intent,
+     scope, related-surface survey, data model, business rules, integration
+     boundaries, architecture approaches. Resolve them with the user by
+     interviewing in rounds over a decision tree: each round asks every currently
+     answerable question (numbered, each with a recommended answer); keep going
+     until no doubt is left unresolved and nothing is silently assumed. -->
+
+- <!-- question -->
+
+## User Answers
+
+<!-- The user's responses, captured verbatim or summarized. -->
+
+- <!-- answer -->
+
+## Related-Surface Survey
+
+<!-- 关联场景清点：every consumer of the capability being changed, grounded in
+     code evidence (file/class/method): 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). 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. -->
+
+- <!-- entry point / shared logic / downstream consumer + code evidence + scoping verdict -->
+
+## Architecture Direction
+
+<!-- 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
+     the HARD-GATE output — proposal, specs, design, and tasks must stay consistent
+     with what is recorded here. -->
+
+## Authoring Tier
+
+<!-- SIMPLE or COMPLEX, with a one-line rationale (criteria in the clarify
+     instruction's Phase 2). SIMPLE: orchestrating agent writes proposal →
+     specs → design → tasks itself. COMPLEX: one generation subagent writes
+     them. Recorded here for auditability before Phase 2 starts. -->
+
+- Tier: <!-- SIMPLE / COMPLEX -->
+- Rationale: <!-- one line -->
+
+## Initial Capabilities
+
+<!-- Preliminary guess of which specs will be created or modified (kebab-case names).
+     Finalized in proposal.md Capabilities section. -->
+
+- `<name>`: <!-- what this capability covers -->

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

@@ -0,0 +1,31 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale. For each: the choice, why, and alternatives considered. -->
+
+## Data Model
+
+<!-- MANDATORY when the change involves persistence. Complete DDL: CREATE TABLE with
+     columns, types, constraints; field descriptions; indexes; audit fields.
+     Follow the project's persistence conventions (AGENTS.md / openspec/config.yaml
+     rules: table prefix, primary key strategy, logical delete, audit columns).
+     If no persistence, state that explicitly. -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs. Format: [Risk] → Mitigation -->
+
+## Open Questions
+
+<!-- Outstanding decisions or unknowns to resolve -->

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

@@ -0,0 +1,32 @@
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Related Surface
+
+<!-- 关联场景：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"
+     without search evidence counts as an incomplete proposal. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
+- `<existing-name>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

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

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

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

@@ -0,0 +1,41 @@
+<!--
+  模板说明：每个 ## N. 是一个独立迭代（task group），编排工具会逐个处理。
+  每个迭代必须自带质量保证：实现代码 + 测试 + 项目质量门（见 AGENTS.md）。
+  每组必须以实质变更为主体：至少一个任务承载真实的代码/配置行为变更（实现 + 测试）。
+  任务组划分必须覆盖 proposal「关联场景」小节划入本 change 的全部消费入口。
+  禁止把纯验证工作（质量门、端到端/回归/冒烟/残留检索）设为独立
+  任务组——无论单独成组还是混入文档/脚本同步拼成「收尾验证组」；文档/脚本同步
+  与验证只是功能组的随行任务，末位剩余工作只剩同步与验证时并入前一个功能组，
+  禁止新开收尾组，组标题以交付的业务价值命名。
+
+  > **各组**可独立实施，组内全部完成后编译通过、可启动、测试通过。
+  > **序号**即实施顺序——跨组依赖确保上游组提交后下游组可对接。
+  > 每个源文件在 tasks.md 中最多出现**一次**（避免跨组并行修改冲突）。
+-->
+
+> **前置 change：** 本 change 依赖 <name> change 完成后才可开始。参见 openspec/changes/<name>/。
+
+## 1. <迭代名称：业务价值或功能名称>
+
+<!-- 本组 4-8 个任务。独立迭代：实现 + 测试 + 质量门。
+     组内任务按依赖链排列：定义 → 实现 → 测试 → 质量门。
+     每个任务以 [spec:<capability>#<requirement>] 标注追溯（纯横切基础设施任务标 [infra]）。 -->
+
+- [ ] 1.1 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 1.2 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 1.3 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 1.4 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 1.5 <!-- 测试：UT + IT --> [spec:<capability>]
+- [ ] 1.6 <!-- 质量门：项目质量门通过（见 AGENTS.md） --> [infra]
+
+## 2. <迭代名称：业务价值或功能名称>
+
+<!-- 本组 4-8 个任务。独立迭代：实现 + 测试 + 质量门。
+     组内任务按依赖链排列：定义 → 实现 → 测试 → 质量门。 -->
+
+- [ ] 2.1 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 2.2 <!-- 任务描述 --> [spec:<capability>#<requirement>]
+- [ ] 2.3 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 2.4 <!-- 任务描述 --> [spec:<capability>]
+- [ ] 2.5 <!-- 测试 --> [spec:<capability>]
+- [ ] 2.6 <!-- 质量门 --> [infra]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.134.0",
+  "version": "0.136.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:
-      "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突时中止并返回 blocked（保留 worktree/分支）。",
+      "完成任务组收尾：合并 task-group 分支到 baseBranch → 清理 worktree 与分支。须在收尾验证（verify_cleanup）通过后调用。合并冲突、主仓库本地改动文件与合并写入文件重合、或存在部分暂存文件时中止并返回 blocked（保留 worktree/分支）；主仓库无关脏文件不阻塞合并。",
     schema: completeTaskGroupSchema,
     execute: (args, ctx) => completeTaskGroupExecute(args as any, ctx),
   },

package/src/core/git.ts

@@ -216,19 +216,86 @@ export async function markTaskGroupCheckboxesComplete(
   }
 }
 
+/** 单条 `git status --porcelain` 条目：XY 状态码 + 涉及路径（重命名条目含 old/new 双路径）。 */
+interface StatusEntry {
+  x: string
+  y: string
+  paths: string[]
+}
+
+/** 去除 porcelain/diff 输出中路径的包裹引号（特殊字符路径会被 git 以双引号包裹）。 */
+function unquotePath(p: string): string {
+  const t = p.trim()
+  return t.startsWith('"') && t.endsWith('"') && t.length >= 2 ? t.slice(1, -1) : t
+}
+
+/**
+ * 解析 `git status --porcelain` 为结构化条目（独立于 parsePorcelainPaths，后者仅取新路径且被
+ * detectChanges / reconcileMainPollution 依赖，语义不可原地变更）。
+ * 重命名条目（`R  old -> new`）双向路径都计入——两侧路径都可能与合并写入清单重合。
+ *
+ * 注意：GitRunner 的 run/runChecked 都对 stdout 整体 trim()，porcelain 首行若以空格开头（X=' ' 的
+ * 未暂存条目）会被吃掉前导空格、列位整体左移一格。porcelain v1 的位置 2 恒为分隔空格，据此识别
+ * 被破坏的首行并补正。
+ */
+function parseStatusEntries(out: string): StatusEntry[] {
+  const entries: StatusEntry[] = []
+  for (const raw of out.split("\n")) {
+    if (raw.length < 4) continue
+    let line = raw
+    if (line[2] !== " ") {
+      // 位置 2 非分隔空格 = 首行被整体 trim 破坏（X=' ' 条目吃掉前导空格，列位左移一格）
+      if (line[1] !== " ") continue
+      line = ` ${line}`
+    }
+    if (line[0] === " " && line[1] === " ") continue
+    const pathPart = line.slice(3)
+    const arrow = pathPart.indexOf(" -> ")
+    const paths = arrow >= 0
+      ? [unquotePath(pathPart.slice(0, arrow)), unquotePath(pathPart.slice(arrow + 4))]
+      : [unquotePath(pathPart)]
+    if (paths.every((p) => p !== "")) entries.push({ x: line[0], y: line[1], paths })
+  }
+  return entries
+}
+
+/** 解析 `git diff --name-only` 输出为路径列表（含引号路径解包）。 */
+function parseDiffNameOnly(out: string): string[] {
+  return out.split("\n").map(unquotePath).filter(Boolean)
+}
+
+/**
+ * 两条路径是否重合（脏文件 ↔ 合并将写入文件）：尾斜杠归一后相等（未跟踪目录 `dir/` 与文件 `dir`
+ * 同名冲突），或互为路径段前缀（未跟踪目录 `dir/` 覆盖目录下任意写入路径，双向判定）。
+ */
+function pathsOverlap(a: string, b: string): boolean {
+  const na = a.replace(/\/+$/, "")
+  const nb = b.replace(/\/+$/, "")
+  if (!na || !nb) return false
+  if (na === nb) return true
+  return na.startsWith(`${nb}/`) || nb.startsWith(`${na}/`)
+}
+
 /**
  * 收尾合并：将任务组分支合并进基础分支。
  *
  * 先解析主仓库根（后续命令一律以主仓库根为 -C 目标，不沿用入参目录），再按目标分支的检出状态分流：
- * 1. `merge-base --is-ancestor` 幂等检查：源分支已是目标分支祖先（如人工解决冲突后重调）直接成功，
- *    不产生空合并提交；
+ * 1. `merge-base --is-ancestor` 幂等检查（重试幂等根基，禁止移除）：源分支已是目标分支祖先
+ *    （如人工解决冲突后重调）直接成功，不产生空合并提交；
  * 2. 检出检测（`worktree list --porcelain`，按目标分支匹配 `branch refs/heads/<X>` 行）：
- *    - 目标分支正被其它 linked worktree 检出，或正被主仓库检出且主仓库有未提交改动 →
- *      返回 blockedMessage（未执行任何 git 变更动作，由上层转 blocked 文案）——
- *      单靠 update-ref 推进分支指针会使检出方暂存区/工作区与分支引用失步（status 显示整套反向改动）；
- *    - 目标分支正被主仓库检出且干净：仍先 `merge-tree --write-tree` 内存试算（冲突零副作用返回），
- *      无冲突则执行真实 `git merge --no-ff`（由 git 维护检出方 index/工作区；失败时 `merge --abort`
- *      兜底恢复后按冲突形态返回，理论上仅竞态会走到此分支）；
+ *    - 目标分支正被其它 linked worktree 检出 → 返回 blockedMessage（未执行任何 git 变更动作，
+ *      由上层转 blocked 文案）——单靠 update-ref 推进分支指针会使检出方暂存区/工作区与分支引用失步
+ *      （status 显示整套反向改动）；
+ *    - 目标分支正被主仓库检出（无论是否干净）：先 `merge-tree --write-tree` 内存拟合并
+ *      （零副作用；退出码 1 = 冲突，按冲突形态返回），无冲突时以拟合并产出树精确计算
+ *      「合并将写入的文件清单」，与主仓库脏文件（已暂存/未暂存/未跟踪；重命名双向路径；
+ *      未跟踪目录按路径段前缀双向匹配）求重合后分流：
+ *      * 有重合 → blocked（列出重合文件；真实合并会覆盖本地改动，交由人工处理）；
+ *      * 无重合且存在已暂存改动 → 完整暂存（暂存内容与工作区一致）时走无损路径：
+ *        `restore --staged` → 真实合并 → finally `git add` 还原暂存态（合并不触碰这些文件）；
+ *        部分暂存（同一文件既有已暂存又有未暂存改动）→ blocked（自动操作会破坏暂存粒度）；
+ *      * 无重合且仅未暂存/未跟踪脏 → 直接真实 `git merge --no-ff`（git 对无关脏文件安全保留；
+ *        失败时 `merge --abort` 兜底恢复）；
  * 3. 无人检出（worktreeless 底层命令，主仓库工作区状态不受影响；冲突时目标分支引用未动、磁盘无半成品）：
  *    `merge-tree --write-tree`（需 git ≥ 2.38）内存试算合并树：退出码 1 = 冲突，直接返回；
  *    `commit-tree` 生成双父合并提交，`update-ref` 以试算前目标分支 oid 作旧值校验推进（CAS，防并发覆盖）。
@@ -261,17 +328,6 @@ export async function mergeBranchToTarget(
         ].join("\n"),
       }
     }
-    const status = await runGit(mainRepo, ["status", "--porcelain"])
-    if (status.trim().length > 0) {
-      return {
-        success: false,
-        conflict: false,
-        blockedMessage: [
-          `- **原因**: 目标分支 \`${targetBranch}\` 正被主仓库检出，且主仓库存在未提交改动；为避免覆盖本地改动，本次未执行任何合并动作（分支引用未动、无半成品）。`,
-          `- **处理**: 请先 commit 或 stash 主仓库改动后重试；或自行执行 \`git merge ${sourceBranch}\`（真实合并自带脏工作区保护）。`,
-        ].join("\n"),
-      }
-    }
     const mergeTree = await runGitChecked(mainRepo, ["merge-tree", "--write-tree", "--messages", targetBranch, sourceBranch])
     if (!mergeTree.success) {
       // merge-tree 退出码 1 = 冲突；其余为分支缺失等真实错误
@@ -280,9 +336,76 @@ export async function mergeBranchToTarget(
       }
       return { success: false, conflict: true }
     }
+    const mergedTreeOid = mergeTree.stdout.split("\n")[0].trim()
+
+    const statusRes = await runGitChecked(mainRepo, ["status", "--porcelain"])
+    if (!statusRes.success) {
+      throw new Error(`无法读取主仓库工作区状态：${statusRes.stderr}`)
+    }
+    const entries = parseStatusEntries(statusRes.stdout)
+
+    if (entries.length > 0) {
+      const dirtyPaths = [...new Set(entries.flatMap((e) => e.paths))]
+      const written = parseDiffNameOnly(
+        await runGit(mainRepo, ["diff", "--name-only", "--no-renames", targetBranch, mergedTreeOid]),
+      )
+      const overlap = written.filter((w) => dirtyPaths.some((d) => pathsOverlap(d, w)))
+      if (overlap.length > 0) {
+        return {
+          success: false,
+          conflict: false,
+          blockedMessage: [
+            `- **原因**: 目标分支 \`${targetBranch}\` 正被主仓库检出，且以下本地改动文件与任务组合并将写入的文件重合；为避免覆盖本地改动，本次未执行任何合并动作（分支引用未动、无半成品）：`,
+            ...overlap.map((f) => `  - \`${f}\``),
+            `- **处理**: 请先 commit/stash/移除上述文件的本地改动后重试；或自行执行 \`git merge ${sourceBranch}\`（真实合并自带脏工作区保护）。`,
+          ].join("\n"),
+        }
+      }
+
+      // 已暂存条目：X 列非空且非 ?（?? 为未跟踪）；重命名双向路径都须纳入还原
+      const stagedPaths = [...new Set(entries.filter((e) => e.x !== " " && e.x !== "?").flatMap((e) => e.paths))]
+      if (stagedPaths.length > 0) {
+        // 完整暂存判定：暂存区与工作区无差异。git merge 对 index 相对 HEAD 的任何差异一律拒绝
+        // （与合并是否重合无关），需先取消暂存绕行；部分暂存场景自动还原会丢失暂存粒度，拒绝代劳。
+        const unstagedDelta = await runGit(mainRepo, ["diff", "--name-only", "--", ...stagedPaths])
+        if (parseDiffNameOnly(unstagedDelta).length > 0) {
+          return {
+            success: false,
+            conflict: false,
+            blockedMessage: [
+              `- **原因**: 主仓库存在部分暂存文件（同一文件既有已暂存又有未暂存改动），自动合并会改变暂存粒度；本次未执行任何合并动作（分支引用未动、无半成品）。`,
+              `- **处理**: 请先 commit 或 stash，或补全/取消暂存后重试；或自行执行 \`git merge ${sourceBranch}\`。`,
+            ].join("\n"),
+          }
+        }
+        // 无损路径：取消暂存 → 真实合并（不触碰这些文件）→ 兜底重新暂存还原
+        let unstagedByUs = false
+        try {
+          const restore = await runGitChecked(mainRepo, ["restore", "--staged", "--", ...stagedPaths])
+          if (!restore.success) throw new Error(`git restore --staged 失败（未执行合并）：${restore.stderr}`)
+          unstagedByUs = true
+          const mergeResult = await runGitChecked(mainRepo, ["merge", "--no-ff", sourceBranch])
+          if (!mergeResult.success) {
+            // 理论上仅竞态会走到此分支：兜底中止，避免主仓库停留在合并中间态
+            await runGitChecked(mainRepo, ["merge", "--abort"])
+            return { success: false, conflict: true }
+          }
+          return { success: true, conflict: false }
+        } finally {
+          if (unstagedByUs) {
+            const readd = await runGitChecked(mainRepo, ["add", "--", ...stagedPaths])
+            if (!readd.success) {
+              // 暂存态还原失败不可静默：合并已发生，抛错让上层感知（重试时 is-ancestor 幂等短路）
+              throw new Error(`合并后还原暂存态失败（git add）：${readd.stderr}；请人工核对这些文件的暂存状态`)
+            }
+          }
+        }
+      }
+    }
+
     const mergeResult = await runGitChecked(mainRepo, ["merge", "--no-ff", sourceBranch])
     if (!mergeResult.success) {
-      // 理论上仅竞态会走到此分支：兜底中止，避免主仓库停留在合并中间态
+      // 兜底中止，避免主仓库停留在合并中间态（无重合脏文件时 git 自身保护仍会拒绝越界写入）
       await runGitChecked(mainRepo, ["merge", "--abort"])
       return { success: false, conflict: true }
     }