@ifrankwang/openspec-agents 0.133.0 → 0.133.2

package/assets/skills/orchestrator/SKILL.md

@@ -29,6 +29,7 @@ capabilities: ["orchestrator"]
   2. 若未初始化，调用初始化工具（如 `mcp__opx__orch_init`）传入 `change_id` / `task_group_id`；
   3. 若 worktree 未就绪，调用 `mcp__opx__orch_set_worktree`（或列表中对应工具）；
   4. 再次调用状态查询工具获取权威「下一步」并严格按返回执行。
+- 用户仅给出 change 名（未指定任务组）时的约定语义：表示以简单模式串行实施该 change 的全部任务组。先读取 `openspec/changes/<change 名>/tasks.md` 获取任务组清单与顺序（该文件是编排规划清单，非被编排项目的业务源码，也是初始化前唯一允许读取的项目文件）：未初始化时从清单第一个任务组开始，以显式 `mode="simple"` 调用初始化工具；当前任务组收尾完成后初始化顺序中的下一个任务组，直至全部任务组完成后编排结束。用户明确指定任务组或要求 full 模式时按用户指定执行，不适用本约定。
 - 子代理工具命名随 harness 不同：
   - DSH 形态：`openspec_developer` / `openspec_reviewer` 两个物理子代理（`openspec_<role>`，物理 agent 已收敛，9 种逻辑身份经 `_agent` 参数承载），分派时直接调用这些专用工具，不要使用通用 `subagent` 代替；
   - 其他 harness 按各自原生子代理机制分派（Claude Code / Codex / ZCode 插件已注入对应子代理）。
@@ -51,7 +52,7 @@ capabilities: ["orchestrator"]
 - 断点续传：子代理因步骤限制中断后重新分派即可继续，无需保存已完成子任务列表
 - 工具列出多个子代理时并排分派（单条消息中同时发送），不串行等待
 - 分派前校验分派 prompt：按「禁止事项」中禁止转述的动态内容清单逐项检查，校验通过后再分派
-- 先解锁、后 status、再探索；禁止在首次 status 前手动探查项目文件/状态文件
+- 先解锁、后 status、再探索；禁止在首次 status 前手动探查项目文件/状态文件（唯一例外：用户未指定任务组时，按启动编排约定语义读取 tasks.md 确定任务组清单与顺序）
 
 ## 禁止事项
 

package/dsh/cordis.patch.yml

@@ -25,47 +25,6 @@
         includeDefaultRoots: false
         customSkillDirs:
           - !!js "process.getBuiltinModule('node:url').fileURLToPath(new URL('./node_modules/@ifrankwang/openspec-agents/assets/skills', baseUrl))"
-    - id: openspec-subagent-developer
-      name: '@deepseek-ai/dsh-tool-subagent'
-      config:
-        provider: spawn
-        toolName: openspec_developer
-        persona: |-
-          ## DSH 工具接入（必读）
-
-          - 本流程的 opx_* 工具在 DSH 中以 `mcp__opx__*` 形式出现，子代理通常只需要：
-            - `mcp__opx__status`
-            - `mcp__opx__agent_submit`
-          - 如果当前工具列表中没有这些工具，请立即调用 `dev_tool_search` 搜索 `opx`，或一次性解锁：
-            ```json
-            {"toolNames": ["mcp__opx__status", "mcp__opx__agent_submit"]}
-            ```
-            如果计划使用 `todo_write` 跟踪任务，也请在同一轮一并解锁。
-          - 严禁使用 `find` / `which` / `grep` 等 shell 命令搜索 `opx`、`openspec`、MCP 配置或安装路径；工具未出现是因为尚未解锁，不是未安装。
-          - 解锁后第一件事是调用 `mcp__opx__status` 获取上下文，不要先探查仓库或读取状态文件。
-
-
-          OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者逻辑身份）。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
-
-          ## 角色（开发者身份）
-
-          你是后端开发工程师，专注于实现 OpenSpec 任务组中的代码开发任务，同时是质量门与接口测试的执行责任人：确定性检查与接口测试由你执行并经自检申报留痕，自检申报是 reviewer 分级复验的事实输入。
-
-          提交前按已加载 skill（含质量维度规范类）完成自检，审查兜底与终局裁定仍由对应 reviewer 承担（自检不替代 reviewer 裁定）。
-
-          自证/验证启动的服务与基础设施一律隔离启动、用后即停，自证完成即清理，不留残留。隔离对象不限于数据库（mock 服务、消息队列/缓存等中间件、扫描分析平台均按隔离标识隔离）。
-
-          任务执行与提交约束（Task/Issue 清单处理、环境问题处置、blocker 提交、文档读取范围、工具调用边界）以 opx_status 操作指引与约束区块为准，此处不重复描述。
-
-          修复的 issue 进入待复核，终态由提出者（对应 reviewer）裁定；被驳回后按修复未过次数门槛处理。
-
-          收尾阶段承担基准分支同步、合并冲突解决、回归复验与隔离环境清理职责；收尾验证中自报 issue 由自己复核收敛（区别于「修复的 issue 进入待复核，终态由提出者裁定」的常规路径）。
-
-          ## 压制处理（开发者身份）
-
-          确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），属豁免申请范畴：必须在压制处代码注释说明清楚理由（commit message 可补充），交由报源审查者判定合理性；不得以压制手段冒充修复。豁免被驳回后，须移除压制并真实修复。
-        enableRunInBackground: false
-        backgroundMode: one-shot
     - id: openspec-subagent-reviewer
       name: '@deepseek-ai/dsh-tool-subagent'
       config:
@@ -282,4 +241,45 @@
           确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），一律视为豁免申请，须判定其合理性：可接受情形（无法消除的框架/第三方限制、有证据的误报，且风险可控、理由充分）→ 认可豁免；不可接受情形（真实缺陷被压制规避、仅图省事、无理由或理由不成立）→ 不认可，须要求移除压制并真实修复。判定时核验压制处的理由（代码注释、commit message）；不认可时须给出可见的判定理由（写入问题描述/建议或驳回说明）。此判定适用于承担工具检查的审查身份（工具审查者、simple 合并审查者）。
         enableRunInBackground: false
         backgroundMode: one-shot
+    - id: openspec-subagent-developer
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: openspec_developer
+        persona: |-
+          ## DSH 工具接入（必读）
+
+          - 本流程的 opx_* 工具在 DSH 中以 `mcp__opx__*` 形式出现，子代理通常只需要：
+            - `mcp__opx__status`
+            - `mcp__opx__agent_submit`
+          - 如果当前工具列表中没有这些工具，请立即调用 `dev_tool_search` 搜索 `opx`，或一次性解锁：
+            ```json
+            {"toolNames": ["mcp__opx__status", "mcp__opx__agent_submit"]}
+            ```
+            如果计划使用 `todo_write` 跟踪任务，也请在同一轮一并解锁。
+          - 严禁使用 `find` / `which` / `grep` 等 shell 命令搜索 `opx`、`openspec`、MCP 配置或安装路径；工具未出现是因为尚未解锁，不是未安装。
+          - 解锁后第一件事是调用 `mcp__opx__status` 获取上下文，不要先探查仓库或读取状态文件。
+
+
+          OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者逻辑身份）。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
+
+          ## 角色（开发者身份）
+
+          你是后端开发工程师，专注于实现 OpenSpec 任务组中的代码开发任务，同时是质量门与接口测试的执行责任人：确定性检查与接口测试由你执行并经自检申报留痕，自检申报是 reviewer 分级复验的事实输入。
+
+          提交前按已加载 skill（含质量维度规范类）完成自检，审查兜底与终局裁定仍由对应 reviewer 承担（自检不替代 reviewer 裁定）。
+
+          自证/验证启动的服务与基础设施一律隔离启动、用后即停，自证完成即清理，不留残留。隔离对象不限于数据库（mock 服务、消息队列/缓存等中间件、扫描分析平台均按隔离标识隔离）。
+
+          任务执行与提交约束（Task/Issue 清单处理、环境问题处置、blocker 提交、文档读取范围、工具调用边界）以 opx_status 操作指引与约束区块为准，此处不重复描述。
+
+          修复的 issue 进入待复核，终态由提出者（对应 reviewer）裁定；被驳回后按修复未过次数门槛处理。
+
+          收尾阶段承担基准分支同步、合并冲突解决、回归复验与隔离环境清理职责；收尾验证中自报 issue 由自己复核收敛（区别于「修复的 issue 进入待复核，终态由提出者裁定」的常规路径）。
+
+          ## 压制处理（开发者身份）
+
+          确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），属豁免申请范畴：必须在压制处代码注释说明清楚理由（commit message 可补充），交由报源审查者判定合理性；不得以压制手段冒充修复。豁免被驳回后，须移除压制并真实修复。
+        enableRunInBackground: false
+        backgroundMode: one-shot
 

package/package.json

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

package/src/core/git.ts

@@ -1,6 +1,6 @@
 import path from "path"
 import { execFile } from "node:child_process"
-import { readFile, writeFile, stat, rm } from "node:fs/promises"
+import { readFile, writeFile, stat, rm, realpath } from "node:fs/promises"
 
 /** 判断路径是否存在于磁盘（fs 层判断，git 命令结果不作为存在性依据）。 */
 async function pathExists(p: string): Promise<boolean> {
@@ -217,30 +217,79 @@ export async function markTaskGroupCheckboxesComplete(
 }
 
 /**
- * 收尾裸合并：将任务组分支合并进基础分支，全程不触碰任何工作目录（worktreeless 底层命令）。
+ * 收尾合并：将任务组分支合并进基础分支。
  *
- * 主仓库工作区状态（当前分支、未提交改动、index）不受影响；冲突时目标分支引用未动、磁盘无半成品。
- * 序列：
+ * 先解析主仓库根（后续命令一律以主仓库根为 -C 目标，不沿用入参目录），再按目标分支的检出状态分流：
  * 1. `merge-base --is-ancestor` 幂等检查：源分支已是目标分支祖先（如人工解决冲突后重调）直接成功，
  *    不产生空合并提交；
- * 2. `merge-tree --write-tree`（需 git ≥ 2.38）内存试算合并树：退出码 1 = 冲突，直接返回；
- * 3. `commit-tree` 生成双父合并提交，`update-ref` 以试算前目标分支 oid 作旧值校验推进（CAS，防并发覆盖）。
+ * 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`
+ *      兜底恢复后按冲突形态返回，理论上仅竞态会走到此分支）；
+ * 3. 无人检出（worktreeless 底层命令，主仓库工作区状态不受影响；冲突时目标分支引用未动、磁盘无半成品）：
+ *    `merge-tree --write-tree`（需 git ≥ 2.38）内存试算合并树：退出码 1 = 冲突，直接返回；
+ *    `commit-tree` 生成双父合并提交，`update-ref` 以试算前目标分支 oid 作旧值校验推进（CAS，防并发覆盖）。
  *
- * @param repoDir 仓库内任意目录（底层命令不读取工作区，不影响 HEAD/index）
+ * @param repoDir 仓库内任意目录（作为主仓库根解析起点）
  */
 export async function mergeBranchToTarget(
   repoDir: string,
   sourceBranch: string,
   targetBranch: string
-): Promise<{ success: boolean; conflict: boolean }> {
-  const ancestor = await runGitChecked(repoDir, ["merge-base", "--is-ancestor", sourceBranch, targetBranch])
+): Promise<{ success: boolean; conflict: boolean; blockedMessage?: string }> {
+  const mainRepo = (await resolveMainRepoRoot(repoDir)) ?? repoDir
+
+  const ancestor = await runGitChecked(mainRepo, ["merge-base", "--is-ancestor", sourceBranch, targetBranch])
   if (ancestor.success) return { success: true, conflict: false }
   // is-ancestor 退出码 1 = 尚未并入（继续合并）；其余为分支缺失等真实错误
   if (ancestor.exitCode !== 1) {
     throw new Error(`无法判断 "${sourceBranch}" 是否已并入 "${targetBranch}"：${ancestor.stderr}`)
   }
 
-  const mergeTree = await runGitChecked(repoDir, ["merge-tree", "--write-tree", "--messages", targetBranch, sourceBranch])
+  const checkedOutPath = await findWorktreeCheckingOut(mainRepo, targetBranch)
+  if (checkedOutPath) {
+    if (!(await sameDir(checkedOutPath, mainRepo))) {
+      return {
+        success: false,
+        conflict: false,
+        blockedMessage: [
+          `- **原因**: 目标分支 \`${targetBranch}\` 正被工作树 \`${checkedOutPath}\` 检出；自动推进分支指针会使该工作树的暂存区/工作区与分支引用失步，本次未执行任何合并动作。`,
+          `- **处理**: 请在该工作树手动执行 \`git merge ${sourceBranch}\`，或移除该工作树（\`git worktree remove ${checkedOutPath}\`）后重试。`,
+        ].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 = 冲突；其余为分支缺失等真实错误
+      if (mergeTree.exitCode !== 1) {
+        throw new Error(`无法试算 "${sourceBranch}" → "${targetBranch}" 的合并：${mergeTree.stderr}`)
+      }
+      return { success: false, conflict: 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 }
+  }
+
+  const mergeTree = await runGitChecked(mainRepo, ["merge-tree", "--write-tree", "--messages", targetBranch, sourceBranch])
   if (!mergeTree.success) {
     // merge-tree 退出码 1 = 冲突；其余为分支缺失等真实错误
     if (mergeTree.exitCode !== 1) {
@@ -251,17 +300,17 @@ export async function mergeBranchToTarget(
   const treeOid = mergeTree.stdout.split("\n")[0].trim()
   if (!treeOid) throw new Error("merge-tree 未返回树对象，无法生成合并提交。")
 
-  const targetOid = (await runGit(repoDir, ["rev-parse", targetBranch])).trim()
-  const sourceOid = (await runGit(repoDir, ["rev-parse", sourceBranch])).trim()
+  const targetOid = (await runGit(mainRepo, ["rev-parse", targetBranch])).trim()
+  const sourceOid = (await runGit(mainRepo, ["rev-parse", sourceBranch])).trim()
   if (!targetOid || !sourceOid) {
     throw new Error(`无法解析分支 OID：target="${targetOid}" source="${sourceOid}"`)
   }
-  const commitOid = (await runGit(repoDir, [
+  const commitOid = (await runGit(mainRepo, [
     "commit-tree", treeOid, "-p", targetOid, "-p", sourceOid, "-m", `Merge branch '${sourceBranch}'`,
   ])).trim()
   if (!commitOid) throw new Error("git commit-tree 失败：无法创建合并提交。")
 
-  const updateRef = await runGitChecked(repoDir, ["update-ref", `refs/heads/${targetBranch}`, commitOid, targetOid])
+  const updateRef = await runGitChecked(mainRepo, ["update-ref", `refs/heads/${targetBranch}`, commitOid, targetOid])
   if (!updateRef.success) {
     throw new Error(`基础分支 "${targetBranch}" 已被并发推进，合并提交未写入（update-ref 旧值校验失败）：${updateRef.stderr}`)
   }
@@ -328,18 +377,53 @@ function parsePorcelainPaths(out: string): string[] {
 }
 
 /**
- * 检测主仓库下 openspec 文档是否存在未提交变更（修改/新增/改名），用于编排者视图的主分支污染诊断。
- * 兼容两种形态：`.git` 为目录（入参即主仓库，repoRoot 取自身）与 `.git` 为文件（走 discoverRepoRoot）。
- * 无法解析主仓库路径或主仓库干净时返回 null。
+ * 解析主仓库根：`.git` 为目录则该目录即主仓库根；`.git` 为文件（linked worktree）时经 discoverRepoRoot 推导。
+ * 解析失败（非 git 仓库等）返回 null，降级行为由调用方决定。
  */
-export async function detectMainRepoPollution(worktreePath: string): Promise<{ repoRoot: string; files: string[] } | null> {
-  let repoRoot: string
+async function resolveMainRepoRoot(worktreePath: string): Promise<string | null> {
   try {
     const st = await stat(path.join(worktreePath, ".git"))
-    repoRoot = st.isDirectory() ? worktreePath : await discoverRepoRoot(worktreePath)
+    return st.isDirectory() ? worktreePath : await discoverRepoRoot(worktreePath)
   } catch {
     return null
   }
+}
+
+/** 跨 symlink 比较两路径是否指向同一目录（macOS /tmp → /private/tmp 等形态）；realpath 失败退回字面 resolve 比较。 */
+async function sameDir(a: string, b: string): Promise<boolean> {
+  try {
+    return (await realpath(a)) === (await realpath(b))
+  } catch {
+    return path.resolve(a) === path.resolve(b)
+  }
+}
+
+/**
+ * 在 `worktree list --porcelain` 输出中查找检出指定分支的 worktree 路径。
+ * porcelain 以空行分块，每块 `worktree <path>` 开头；bare 或 detached 块无 `branch` 行，跳过。
+ */
+async function findWorktreeCheckingOut(repoRoot: string, branch: string): Promise<string | null> {
+  const out = await runGit(repoRoot, ["worktree", "list", "--porcelain"])
+  for (const block of out.split("\n\n")) {
+    let wtPath = ""
+    let wtBranch = ""
+    for (const line of block.split("\n")) {
+      if (line.startsWith("worktree ")) wtPath = line.slice("worktree ".length).trim()
+      else if (line.startsWith("branch ")) wtBranch = line.slice("branch ".length).trim()
+    }
+    if (wtPath && wtBranch === `refs/heads/${branch}`) return wtPath
+  }
+  return null
+}
+
+/**
+ * 检测主仓库下 openspec 文档是否存在未提交变更（修改/新增/改名），用于编排者视图的主分支污染诊断。
+ * 兼容两种形态：`.git` 为目录（入参即主仓库，repoRoot 取自身）与 `.git` 为文件（走 discoverRepoRoot）。
+ * 无法解析主仓库路径或主仓库干净时返回 null。
+ */
+export async function detectMainRepoPollution(worktreePath: string): Promise<{ repoRoot: string; files: string[] } | null> {
+  const repoRoot = await resolveMainRepoRoot(worktreePath)
+  if (!repoRoot) return null
   // 健壮性：git 调用失败（如非 git 仓库/权限/损坏）时返回 null，不使 opx_status 整体抛错；
   // 污染诊断属编排者视图的辅助信息，缺失不应阻断状态视图渲染。
   let out: string

package/src/core/tools/lifecycle.ts

@@ -1144,6 +1144,9 @@ export async function completeTaskGroupExecute(params: { change_id: string }, ct
   const mergeTarget = state.baseBranch
   if (branchName && !isReviewNone) {
     const mergeResult = await mergeBranchToTarget(ctx.worktree, branchName, mergeTarget)
+    if (mergeResult.blockedMessage) {
+      return [`- **status**: blocked`, mergeResult.blockedMessage].join("\n")
+    }
     if (!mergeResult.success) {
       return [
         `- **status**: blocked`,