@ifrankwang/openspec-agents 0.126.0 → 0.128.0

package/.mcp-server/cli.mjs

@@ -29434,6 +29434,9 @@ function agentToReviewLayer(agent) {
     return "quality";
   return;
 }
+function isReviewerFamily(agent) {
+  return agent === "openspec-architect" || agentToReviewLayer(agent) !== undefined;
+}
 function readIssueSource(child) {
   return typeof child.metadata["source"] === "string" ? child.metadata["source"] : undefined;
 }
@@ -29719,6 +29722,39 @@ async function reconcileMainPollution(mainRepo, worktreePath, opts) {
     }
   }
 }
+async function autoCommitWorktreeChanges(wtPath, agent, stepId) {
+  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain"]);
+  if (!statusRes.success) {
+    return { status: "failed", files: [], untrackedFiles: [], stderr: statusRes.stderr };
+  }
+  const files = [];
+  const untrackedFiles = [];
+  for (const line of statusRes.stdout.split(`
+`).map((l) => l.trim()).filter(Boolean)) {
+    const path2 = parsePorcelainPaths(line)[0];
+    if (!path2 || path2.startsWith("openspec/states/"))
+      continue;
+    if (line.startsWith("??"))
+      untrackedFiles.push(path2);
+    else
+      files.push(path2);
+  }
+  if (files.length === 0)
+    return { status: "skipped", files: [], untrackedFiles };
+  const addResult = await runGitChecked(wtPath, ["add", "-u", "--", ".", ":(exclude)openspec/states"]);
+  if (!addResult.success) {
+    return { status: "failed", files, untrackedFiles, stderr: addResult.stderr };
+  }
+  const commitResult = await runGitChecked(wtPath, [
+    "commit",
+    "-m",
+    `docs(opx): direct fixes by ${agent} (${stepId})`
+  ]);
+  if (!commitResult.success) {
+    return { status: "failed", files, untrackedFiles, stderr: commitResult.stderr };
+  }
+  return { status: "committed", files, untrackedFiles };
+}
 
 // src/core/state.ts
 import path2 from "path";
@@ -35738,6 +35774,15 @@ function assertValidRecovery(recovery) {
     }
   }
 }
+function otherTaskGroupsSettled(state, targetGroupId) {
+  return state.workItems.filter((w) => w.id.startsWith("task:") && w.id !== `task:${targetGroupId}`).every((item) => {
+    if (item.phase === "done" || item.metadata["completed_at"] !== undefined)
+      return true;
+    const noTags = Object.keys(item.tags).length === 0;
+    const childrenSettled = item.children.filter((c) => c.type === "task").every((c) => c.phase === "todo" || isTerminalPhase(c.phase));
+    return noTags && childrenSettled;
+  });
+}
 async function initExecute(params, ctx) {
   assertOrchestrator(ctx, "opx_orch_init");
   const args = { ...params };
@@ -35780,6 +35825,19 @@ async function initExecute(params, ctx) {
   const baseBranch = args.base_branch || await getCurrentBranch(ctx.worktree);
   let state = await readStateByChangeId(ctx.worktree, args.change_id);
   const wasCurrentGroup = state?.taskGroupId === args.task_group_id;
+  let modeSwitchNote = null;
+  if (state && args.mode !== undefined && args.mode !== (state.mode ?? "full")) {
+    const othersSettled = otherTaskGroupsSettled(state, args.task_group_id);
+    const withinWindow = (args.task_group_id !== state.taskGroupId || args.recovery?.phase === "task_analysis") && othersSettled;
+    if (!withinWindow) {
+      throw new Error(`mode 参数与已固化的流程模式不一致：已固化 mode="${state.mode ?? "full"}"${state.mode === undefined ? "（旧变更未固化，读取时兜底 full）" : ""}，传入值："${args.mode}"。
+` + `当前场景不允许切换流程模式：切换任务组须其他任务组均已完成或从未激活；重制当前组仅支持 recovery.phase="task_analysis"（其他任务组同样须已完成或从未激活）。
+` + `请去掉 mode 参数继续沿用固化模式，或满足上述窗口条件后再切换。`);
+    }
+    const prevMode = state.mode;
+    state.mode = args.mode;
+    modeSwitchNote = `流程模式已从 ${prevMode ?? "full"} 切换为 ${args.mode}。`;
+  }
   if (!state) {
     state = {
       changeId: args.change_id,
@@ -35880,7 +35938,12 @@ async function initExecute(params, ctx) {
   }
   state.taskGroupId = args.task_group_id;
   await writeState(ctx.worktree, state);
-  return args.recovery ? `编排会话已初始化。已恢复到 ${args.recovery.phase} 阶段。` : "编排会话已初始化。";
+  const parts = ["编排会话已初始化。"];
+  if (args.recovery)
+    parts.push(`已恢复到 ${args.recovery.phase} 阶段。`);
+  if (modeSwitchNote)
+    parts.push(modeSwitchNote);
+  return parts.join("");
 }
 async function bindWorktreeRefs(item, worktreePath, branch, baseBranch, opts = {}) {
   item.metadata["worktree_path"] = worktreePath;
@@ -36554,6 +36617,18 @@ async function agentSubmitExecute(params, ctx) {
       exemptIds: params.exempt_issue_ids,
       newChildren: accepted
     });
+    const autoCommitLines = [];
+    if (isReviewerFamily(ctx.agent)) {
+      const ac = await autoCommitWorktreeChanges(wtPath, ctx.agent, params.step_id);
+      if (ac.status === "committed") {
+        autoCommitLines.push(`- ✅ worktree 直改修正已自动提交（${ac.files.length} 个文件，commit message: \`docs(opx): direct fixes by ${ctx.agent} (${params.step_id})\`）`);
+      } else if (ac.status === "failed") {
+        autoCommitLines.push(`- ⚠️ worktree 直改修正自动提交失败：${ac.stderr || "未知错误"}。请编排者安排补提交（worktree 内 git add -u 后 commit）`);
+      }
+      if (ac.untrackedFiles.length > 0) {
+        autoCommitLines.push(`- ⚠️ 存在未跟踪新建文件未纳入自动提交（须纳入版本控制时由编排者/开发者处理）：${ac.untrackedFiles.join("、")}`);
+      }
+    }
     if (stepPhase === "todo" && params.step_id === "analyze" && params.verdict === "passed" && wtPath && typeof item.metadata["branch_name"] === "string") {
       const baseRef = typeof item.metadata["base_ref"] === "string" ? item.metadata["base_ref"] : null;
       await reconcileMainPollution(ctx.worktree, wtPath, {
@@ -36570,7 +36645,17 @@ async function agentSubmitExecute(params, ctx) {
       await writeDismissedExemption(ctx.worktree, child, { changeId: state.changeId, exemptedBy: ctx.agent });
     }
     await writeState(ctx.worktree, state);
-    return SUBMIT_OK_MESSAGE;
+    if (autoCommitLines.length === 0)
+      return SUBMIT_OK_MESSAGE;
+    return [
+      `## ✅ ${SUBMIT_OK_MESSAGE}`,
+      "",
+      "### worktree 自动提交",
+      "",
+      ...autoCommitLines,
+      ""
+    ].join(`
+`);
   } finally {
     releaseLock(lockPath);
   }
@@ -36848,7 +36933,7 @@ var orchInitSchema = {
     mode: {
       type: "string",
       enum: ["full", "simple"],
-      description: "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。仅新建编排状态（首次 opx_orch_init）时生效；已开始的变更沿用固化模式，不支持中途切换。"
+      description: "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。"
     }
   },
   required: ["change_id", "task_group_id"],
@@ -37040,7 +37125,7 @@ function jsonSchemaToZod(schema2) {
 var AGENT_ARG = "_agent";
 var TOOL_SPECS = {
   opx_orch_init: {
-    description: "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式，仅新建状态生效。",
+    description: "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式：首次新建状态时固化；已开始的变更仅切组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）时可更新，其余场景传不同 mode 报错。",
     schema: orchInitSchema,
     execute: (args, ctx) => initExecute(args, ctx)
   },
@@ -37100,7 +37185,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.126.0";
+var PKG_VERSION = "0.128.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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ifrankwang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,129 +1,110 @@
 # openspec-agents
 
-OpenSpec 流程的 Agent Team：面向实施阶段的多 Agent 工作流编排。
+![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
+![Built for OpenSpec](https://img.shields.io/badge/built%20for-OpenSpec-6b46c1.svg)
 
-> 当前定位：把已确定的 OpenSpec change 落地为高质量代码。
-> 未来方向：向前扩展「探索 + 方案制定」，覆盖 OpenSpec 更早期环节。
+> 让多个 AI 智能体按规范流程协作，把 OpenSpec 变更规范落地为经过审查的高质量代码。
 
-## 它解决什么问题
+`openspec-agents` 是一组面向 AI 编码工具的插件，把 OpenSpec 的「需求 → 设计 → 任务拆分」成果，自动推进到「实现 → 验证 → 质量审查 → 收尾合并」的完整实施流程。主智能体负责调度，专职智能体分别承担实现、检查与质量把关，每一步都有门禁确认，全程可审计、可恢复。
 
-OpenSpec 把需求、设计、任务拆解成规范文档后，实施阶段仍然需要多步开发、验证、质量审查和收尾。本项目用一组 Agent 角色 + workflow 引擎，把这一过程编排成可重复、可审计的流水线：
+## 特性
 
-`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`（full 模式；simple 模式见「编排流程」）
+- **多工具支持**：Claude Code、Codex、ZCode、DeepSeek Harness（DSH）、OpenCode 均可原生接入。
+- **规范驱动**：直接消费 OpenSpec 变更规范（proposal / design / tasks / specs），流程与规范一一对应。
+- **智能体团队**：不再是单个 AI 从头写到尾，而是「实现者 + 审查者 + 质量把关者」分工协作，结果更稳。
+- **质量门禁**：实现之后经过工具检查、任务验证与多维度质量审查；发现的问题自动回退修复，也可按规则豁免并留痕。
+- **隔离执行**：每个变更在独立的环境中实施，互不干扰；变更完成后合并并清理。
+- **过程可审计**：进度、结论、豁免与恢复点全程记录，随时可以接着上次的进度继续。
 
-主代理负责调度，子代理负责实施、审查、质量验证和清理；所有裁决通过统一 `opx_*` 工具提交，状态持久化到仓库内。
+## 快速开始
 
-## 编排流程
+1. 准备环境：**Node.js ≥ 23.6**（或 Bun）与 **git**。
+2. 按下方「安装」选择你正在使用的 AI 工具完成安装。
+3. 重启该工具后，把下面「一句话接入」的提示词发给你的 AI 即可开始。
 
-实施流程按变更开始时固化的模式执行：模式经 `opx_orch_init` 的 `mode` 参数在变更开始时固化（`full` 完整流程 / `simple` 精简流程，不传缺省 simple）。已开始的变更不受后续参数影响；恢复（recovery）沿用固化模式；旧变更（状态无模式存档）一律按 full 处理，不支持中途切换。
+## 安装
 
-### full 模式
+按你使用的 AI 工具选择一种方式：
 
-`analyze → implement → verify_tool → verify_task → verify_quality → verify_cleanup → done`
+### Claude Code
 
-分析、实现、三层审查（工具检查 / 任务验证 / 五维质量审查）与收尾验证逐步推进，问题可回退、可豁免、可检查点决策。
+```bash
+claude plugin marketplace add https://github.com/ifrankwang/claude-code-plugins
+claude plugin install openspec-agents@ifrankwang
+```
+
+### Codex
+
+```bash
+codex plugin marketplace add https://github.com/ifrankwang/codex-plugins
+codex plugin add openspec-agents@ifrankwang
+```
+
+### ZCode
+
+打开 ZCode 插件页，添加市场 `ifrankwang/zcode-plugins`，然后安装 `openspec-agents`。
+
+### DeepSeek Harness（DSH）
+
+```bash
+dsh plugin --profile web add @ifrankwang/openspec-agents
+```
 
-### simple 模式
+安装后重启 `dsh web` 即可。
 
-`implement → quality_review → done`
+### OpenCode
 
-面向轻量变更的精简流程：无 analyze 环节（执行边界默认整个 worktree），无 verify_tool / verify_task / verify_cleanup 环节。implement 失败自循环重试；quality_review 由单一审查者合并承担工具检查、任务验证与质量审查（工具改进建议双报机制保留，由开发者实施），失败回 implement 整步重审；开发者实施时按已加载接口测试规范即时更新并执行 `.http` 接口测试自证变更有效（含关键数据产出断言）；开发者提交 implement 成果时强检查工作区干净（不干净拒绝并提示先 commit），收尾为直接合并分支并清理（裸合并，无回归；环境清理由审查者验证完成后自行完成——停止残留服务、清理隔离环境，收尾不单独承担环境清理；合并冲突由开发者解决后直接收尾）。tasks.md 复选框在任务组收尾（opx_orch_complete_task_group）时统一勾选当前任务组，勾选提交落在 worktree 分支、随合并带回主分支；full 与 simple 行为一致，任务完成状态以状态文件为准。
+```bash
+npm install -D @ifrankwang/openspec-agents
+```
+
+然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件，重启 OpenCode。
+
+## 让 AI 帮你接入（一句话）
+
+安装后（甚至还没安装时），直接把这句提示词发给你的 AI 编码工具：
+
+> 请帮我安装并启用 openspec-agents 插件，然后基于当前项目的 OpenSpec 变更规范，执行完整的变更实施编排流程。
 
-## 身份与角色
+英文版：
 
-物理 agent 定义收敛为两个子代理（`assets/agents/` 下的 `openspec-developer.md`、`openspec-reviewer.md`，主代理模板 `openspec-main.md` 保留），9 种逻辑身份（architect、reviewer-tool、reviewer-task、style / architecture / performance / security / maintainability 五维审查者、simple 审查者）不再有独立定义文件，统一经 `_agent` 参数承载：子代理调用 `opx_*` 工具时传自身角色名，系统按该逻辑身份路由状态视图、issue 来源与筛选、「谁提谁裁定」与状态标识。
+> Please install and enable the openspec-agents plugin for my current AI coding tool, then run the OpenSpec change orchestration workflow on this repository.
 
-- 开发者物理 agent 承载 developer 与 architect 两个逻辑身份；审查者物理 agent 承载 tool / task / 五维 / simple 审查者逻辑身份。full 模式的质量审查以 5 个逻辑身份并行执行——同一物理审查者被多次分派，每次以不同 `_agent` 参数承载对应逻辑身份。
-- 物理权限取各逻辑身份权限并集（维度审查者因此具备编辑与写入能力）；审查行为以「只报不改」指令约束兜底——文档/注释等不影响代码运行的问题可直接修改，逻辑类问题只上报，full 模式同样适用。
-- `_agent` 为纯自述、无硬校验：任何调用者可自报任意身份，裁定权与视图路由均信任自述值；冒认只能以自报身份行事，无法越出该身份自身的既有权限面。
+如果已经安装，只需说一句「请运行 openspec-agents 编排流程」即可开工。AI 会负责完成安装、初始化、任务分派与质量把关的全部步骤。
 
-## 特色
+## 工作原理（简述）
 
-- **Agent 无关**：内核不绑定具体 Agent，opencode / claude code / codex / zcode / deepseek harness 通过各自原生插件/适配器接入同一套状态机。
-- **Workflow 驱动**：步骤、角色、门禁在 workflow 中声明，`opx_status` 是下一步调度的唯一事实源。
-- **多 Agent 团队**：主代理编排，2 个物理子代理承载 9 种逻辑身份分工协作，避免单一大模型从头写到尾失控。
-- **强 Review 门禁**：full 模式 tool / task / quality 三层审查 + 收尾验证；simple 模式单一审查者合并审查。问题可回退、可豁免、可检查点决策。确定性质量工具问题以压制手段解决时视为豁免申请，须说明理由并经审查判定合理性。
-- **隔离与安全**：每个 change 使用独立 git worktree、资源隔离命名空间（数据库、mock 服务、消息队列/缓存等中间件、扫描分析平台均按隔离标识隔离），减少相互干扰。
-- **可观测**：内置进度看板，状态/豁免/并发锁持久化到 `openspec/states/`。
+1. **输入**：项目中的 OpenSpec 变更规范（变更说明、设计、任务清单、验收规格）。
+2. **分派**：主智能体把任务交给专职智能体——实现者负责写代码，审查者负责检查，质量把关者负责多维验证。
+3. **门禁**：每一步的结论通过检查后才进入下一步；不通过的结论自动回到实现环节修复。
+4. **收尾**：变更完成后自动合并分支并清理执行环境，全程留痕可审计。
 
-## 优缺点
+## 适用场景与代价
 
 | | |
 |---|---|
-| 优点 | 产出代码质量高；有明确流程和门禁，结果不会太过偏离目标；过程可审计、可恢复 |
-| 缺点 | 慢（多轮 Agent 调用 + 多级 review）；贵（token/API 消耗高于单 Agent 直接改） |
+| 适合 | 对代码质量、过程可控性要求高的团队与项目 |
+| 代价 | 比单个 AI 直接修改更慢，API 消耗更高 |
 
-适合对质量、可控性要求高，且愿意用成本换稳定产出的实施场景。
+如果你愿意用一点成本换取稳定、可复现、可审计的实施过程，这个项目就是为你准备的。
 
-## 接入方式
+## 开发
 
-项目已为各 Agent 工具提供官方插件/适配器，普通使用时直接按对应工具的原生机制接入即可，无需手动拼装或启动 MCP Server。
+```bash
+bun install            # 安装依赖
+bun test               # 运行测试
+bun run typecheck      # 类型检查
+bun run build:plugins  # 构建各平台的插件包（发布用）
+```
 
-依赖：Node.js ≥ 23.6（或 Bun）、git。
+## 贡献
 
-```bash
-# 安装依赖
-bun install
+欢迎提交 [Issue](https://github.com/ifrankwang/openspec-agents/issues) 与 Pull Request，也欢迎 Star 支持。
 
-# 测试 / 类型检查
-bun test
-bun run typecheck
-```
+## 致谢
 
-各 Agent 接入：
-
-- **OpenCode**：以 npm 插件形式加载，插件注入 agent/skill 与 MCP server 配置（`config.mcp` 的 stdio server，自包含 bundle，`--worktree` 指向当前项目根）。
-  ```bash
-  npm install -D @ifrankwang/openspec-agents
-  ```
-  然后在 OpenCode 配置中加载 `@ifrankwang/openspec-agents` 插件并重启 OpenCode（MCP server 配置在启动时加载）：`opx_*` 工具以 `mcp__opx__*` 形态出现（如 `mcp__opx__status`、`mcp__opx__agent_submit`，serverName=opx），身份经 `_agent` 参数承载（缺省视为编排视角）。
-
-- **Claude Code**：通过官方插件市场安装。
-  ```bash
-  claude plugin marketplace add https://github.com/ifrankwang/claude-code-plugins
-  claude plugin install openspec-agents@ifrankwang
-  ```
-
-- **Codex**：通过官方插件市场安装。
-  ```bash
-  codex plugin marketplace add https://github.com/ifrankwang/codex-plugins
-  codex plugin add openspec-agents@ifrankwang
-  ```
-
-- **ZCode**：在 ZCode 插件页添加市场 `ifrankwang/zcode-plugins`，然后安装 `openspec-agents`。
-
-- **DeepSeek Harness（DSH）**：通过 DSH 的 bundle 插件机制接入。发布到 npm 后可直接安装：
-  ```bash
-  dsh plugin --profile web add @ifrankwang/openspec-agents
-  ```
-  本地开发时也可使用构建产物：
-  ```bash
-  bun run build:plugins
-  dsh plugin --profile web add ./dist/deepseek-harness-plugin
-  ```
-  安装后重启 `dsh web`：
-  - `opx_*` 会以 `mcp__opx__*`（如 `mcp__opx__status`、`mcp__opx__agent_submit`） 原生工具出现；
-  - `assets/skills` 会作为额外 skill 根被扫描；
-  - 每个子代理会注册为 DSH 原生 subagent 工具：`openspec_developer` 与 `openspec_reviewer` 两个物理子代理，编排主代理可直接分派（9 种逻辑身份经 `_agent` 参数承载，同一物理子代理可被多次分派）。
-
-## 常用命令
-
-| 命令 | 说明 |
-|------|------|
-| `bun test` | 运行所有测试 |
-| `bun run typecheck` | TypeScript 类型检查 |
-| `bun run build:plugins` | 构建 Claude Code / Codex / ZCode / DeepSeek Harness 插件包（CI/内部使用） |
-| `bun run sync` | 同步本地最新开发版本到各 harness 插件缓存，并安装/刷新依赖 |
-
-## 项目结构
+本项目基于 [OpenSpec](https://github.com/Fission-AI/OpenSpec)（[openspec.sh](https://openspec.sh)）构建——感谢 OpenSpec 团队带来的规范驱动开发方法：先写规范、再写代码，让 AI 开发有据可依。本插件专注于补全 OpenSpec 变更的**实施与质量把关**环节，是对 OpenSpec 工作流的编排增强。
 
-```
-src/core/                  — Agent 无关内核（状态机、工具执行器、状态持久化）
-src/adapters/              — opencode / claude-code / codex / zcode / deepseek-harness / mcp 适配层
-assets/agents/             — Agent 定义
-assets/skills/             — 内置 skill（含 orchestrator）
-assets/workflows/          — workflow 定义
-tests/                     — 测试
-```
+## 许可证
 
-详细实现见 `AGENTS.md` 与 `src/core/`、`assets/workflows/`。
+[MIT](LICENSE) © 2025 ifrankwang

package/assets/agents/openspec-developer.md

@@ -1,5 +1,5 @@
 ---
-description: OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者与架构师两个逻辑身份）。开发者身份遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug；架构师身份负责文档一致性复核与方案评估。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
+description: OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者逻辑身份）。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
 mode: subagent
 hidden: true
 steps: 200
@@ -26,52 +26,3 @@ permission:
 ## 压制处理（开发者身份）
 
 确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），属豁免申请范畴：必须在压制处代码注释说明清楚理由（commit message 可补充），交由报源审查者判定合理性；不得以压制手段冒充修复。豁免被驳回后，须移除压制并真实修复。
-
-## 角色（架构师身份）
-
-你是架构师，负责**文档一致性复核与方案评估**：以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题（仅限 md 文件——物理权限为并集 edit: allow，架构师身份的行为边界仍限定仅编辑 md 文档，设计/架构验证问题与信息缺口一律走 blocker），信息齐备时输出执行边界、存在缺口时提交 blockers。
-
-需用户拍板的问题由你直接确认——blocker 的用户确认环节归属本身份：有人值守时直接向用户确认（question 工具），无人值守时自行裁决。
-
-## 严重级别（架构师身份 / 架构维度）
-
-使用统一严重级别体系（Critical / High / Medium / Low / Info）。
-
-| 级别 | 本维度典型场景 |
-|------|--------------------------|
-| Critical | design 中的 schema 与实现冲突导致无法建表/编译；tasks 缺失核心步骤导致实施方向错误；实施所需关键信息缺失（如模板路径、字段映射未明），导致无法开始实施；**设计架构方案违反 architecture skill 的 MUST 规则** |
-| High | spec 需求在 tasks 中无对应任务；基础架构任务错排位置；实施所需信息不完整，部分任务需等待补充信息才能推进；**设计方案偏离 architecture skill 推荐做法，存在可通过调整规避的风险** |
-| High | 设计方案破坏既有接口/数据/行为契约且无兼容或过渡安排；重构方案改变既有行为语义且未显式声明 |
-| Medium | tasks 范围模糊；design 技术细节与 tasks 完成标准不一致 |
-| Low | 文档引用路径有冗余前缀；描述用词与 spec 不一致但不影响理解 |
-| Info | 建议补充某边缘场景说明；可 `（待补充）` 占位、不阻塞开工的边缘信息缺失 |
-
-## 审查内容（架构维度）
-
-与 Review 阶段架构维度 reviewer 共用同一套检查点（锚定同一规范源），审查 design.md 方案时逐项核对：
-
-- 分层依赖：按 skill 中的架构分层规则和依赖方向
-- 核心层隔离：按 skill 中领域/业务层对框架的依赖限制
-- 依赖注入：按 skill 中的 DI 方式约定（构造器注入 vs 字段注入）
-- 数据对象：按 skill 中的不可变性/可变性约定
-- 端口/适配器模式：按 skill 中的外部依赖契约定义方式
-- 共性能力基础设施化：按 skill 中的共性能力基础设施化约定——方案中应上收为统一机制的横向逻辑须在设计中落位
-- 接口契约与命名隔离：按 skill 中的外部系统命名隔离约定——外部系统名不得出现在内核与 interfaces 层的接口、方法、DTO 命名中
-- 命名合理性：按 skill 中的通用语言与命名规范——命名体现意图、不与其他场景混淆、与术语表一致防漂移
-- 方案复用与平行实现：按 skill 中的方案复用与平行实现约定——同类能力已有既有实现时（如已有手工限流基础框架仍引入新限流框架且不改动原实现）须优先复用或扩展，确需平行引入（新旧并存）时按上文需用户拍板问题的确认机制确认并存期与技术债，无人值守缺省裁决为方案必须包含原技术实现的迁移方案
-- 技术债识别：按 skill 中的技术债识别约定——方案是否引入可识别技术债（过时技术选型、技术迁移中断、平行引入、临时方案固化、契约不一致），引入的债务须在方案中规划偿还或说明可接受理由
-- 架构演进审查：按 skill 中的架构演进审查约定——方案是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口/数据/行为兼容性）、重构方案是否贴合项目历史逻辑并保持既有行为语义；破坏兼容或偏离架构脉络须在方案中说明理由与过渡安排；涉及字段/实体承载位置搬迁时，方案须明确数据承接与迁移设计：新承载位置、产出字段写入目标、存量数据迁移、旧位置兼容与清理；缺失按既有契约破坏/重构贴合判例报 issue
-
-## 执行边界产出（架构师身份）
-
-`notes` 仅填实施建议，不重复目录/包路径，包含：
-- 关键坑位提醒（本组特有陷阱，避免重复 AGENTS.md 项目通用坑位）
-- 组件复用指引（本组范围内可复用的既有实现）
-- 设计约束的边缘场景说明（design.md 未展开但影响实施的边界条件）
-- 框架应用说明（如对象映射框架使用要点）
-- 通用做法指引：识别任务中是否已存在通用做法（如文件类型拦截、权限身份抽取等），有则注明 dev 须遵循现有做法（任务明确要求换做法除外）；无现成但判断应做成通用做法的，注明拓展性要求
-- 无补充信息时留空（`""`）
-
-取重责任：**不存在由架构师做语义去重**——issue 去重由 reviewer 自身完成（本维度既有 issue 供 reviewer 参考）。
-
-行为约束（按评估维度审查、blocker 处理、工具调用边界、只审当前任务组范围）以 opx_status 操作指引与约束区块为准，此处不重复描述。

package/assets/agents/openspec-reviewer.md

@@ -1,17 +1,19 @@
 ---
-description: OpenSpec 编排流程专用 — 审核人（物理 agent，承载工具 / 任务 / 5 质量维度 / simple 审查者逻辑身份）。统一只报不改：影响代码运行的逻辑类问题只上报，文档/注释类问题可直接修改。仅在 openspec-agents 工作流内由编排者分派使用。
+description: OpenSpec 编排流程专用 — 审核人（物理 agent，承载架构师 + 工具 / 任务 / 5 质量维度 / simple 审查者逻辑身份）。影响代码运行的逻辑类问题只上报；文档/注释类不一致/过时问题直接修正。仅在 openspec-agents 工作流内由编排者分派使用。
 mode: subagent
 hidden: true
 steps: 200
 permission:
   edit: allow
   bash: allow
+  question: allow
 ---
 
 ## 角色
 
 你是审核人（Reviewer），承担 OpenSpec 编排流程的审查职责，按分派时的逻辑身份执行对应审查：
 
+- **架构师**（analyze，方案审查）：文档一致性复核与方案评估——以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题，信息齐备时输出执行边界、存在缺口时提交 blockers
 - **工具维度审查者**（tool review，full 模式三层门禁第一层）：执行确定性工具检查，将工具输出映射为统一 issue 结构；简单（simple）模式亦承担该职责
 - **任务维度审查者**（task review，full 模式三层门禁第二层）：验证 task 产出完整性、启动服务并检查健康、独立执行 API 测试并审查质量、审查测试代码质量；验证完成后清理本变更启动的环境（停止残留服务、清理隔离环境）；简单（simple）模式亦承担该职责
 - **质量维度审查者**（quality review，full 模式三层门禁第三层）：按分派维度（style / architecture / performance / security / maintainability）审查
@@ -21,12 +23,18 @@ permission:
 
 复核自己报的已修复（待复核）issue 属本职职责，通过与否由复核结论裁定。
 
-## 只报不改
+## 角色（架构师身份）
 
-默认只报不改，适用于全部审查身份（含 full 模式的维度审查）：
+你是架构师，负责**文档一致性复核与方案评估**：以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题（仅限 md 文件——物理权限为并集 edit: allow，架构师身份的行为边界仍限定仅编辑 md 文档，设计/架构验证问题与信息缺口一律走 blocker），信息齐备时输出执行边界、存在缺口时提交 blockers。
+
+需用户拍板的问题由你直接确认——blocker 的用户确认环节归属本身份：有人值守时直接向用户确认（question 工具），无人值守时自行裁决。
+
+## 只报不改与文档直改
+
+适用于全部审查身份（含架构师身份与 full 模式的维度审查）：
 
 - 影响代码运行的逻辑类问题：只上报 issue，不直接修改相关代码
-- 文档、注释等不影响代码运行的问题：可直接修改
+- 文档、注释等不影响代码运行的内容：发现不一致/过时问题时直接修正，不为此报 issue；修正情况在提交说明/validation_steps 留痕
 - 工具改进建议仅上报（含规则草案），实施由开发者完成
 
 ## 严重级别
@@ -67,16 +75,15 @@ Info 级别 issue 的 description/suggestion 中禁止出现阶段/时机相关
 
 ### 架构维度判例
 
-| 级别 | 本维度典型场景 |
-|------|--------------|
-| Critical | 核心层依赖框架导致循环依赖或编译失败 |
-| High | 表示层直接绕过领域层访问基础设施 |
-| Medium | 依赖注入方式不符合约定（如字段注入）；数据对象可变导致并发风险；应基础设施化的共性能力被分散实现（多处重复、横向共性需求、新增场景易遗漏调用） |
-| Medium | 引入与既有实现功能重叠的平行实现（另起一套逻辑），同类能力多套方案并存且无迁移方案 |
-| Medium | 引入或延续可识别技术债且无偿还规划（如采用 EOL/弃用技术选型、临时方案长期固化、接口契约不一致） |
-| Medium | 重构/变更破坏既有契约（接口/数据/行为）或改变既有行为语义且无兼容说明 |
-| Low | 数据对象缺少不可变修饰但当前无并发场景；已有代码中违反分层原则但影响极小的结构性缺陷 |
-| Info | 建议拆分为独立服务；建议引入某设计模式（仅当不属于 Low 及以上时） |
+单一权威判例表：架构师身份（审方案文档）与 quality 架构维度（审实施代码）两个视角共用，按所属视角的列取判例。
+
+| 级别 | 实施代码（quality 架构维度） | 方案文档（架构师身份） |
+|------|--------------|--------------------------|
+| Critical | 核心层依赖框架导致循环依赖或编译失败 | design 中的 schema 与实现冲突导致无法建表/编译；tasks 缺失核心步骤导致实施方向错误；实施所需关键信息缺失（如模板路径、字段映射未明），导致无法开始实施；设计架构方案违反 architecture skill 的 MUST 规则 |
+| High | 表示层直接绕过领域层访问基础设施 | spec 需求在 tasks 中无对应任务；基础架构任务错排位置；实施所需信息不完整，部分任务需等待补充信息才能推进；设计方案偏离 architecture skill 推荐做法，存在可通过调整规避的风险；设计方案破坏既有接口/数据/行为契约且无兼容或过渡安排；重构方案改变既有行为语义且未显式声明 |
+| Medium | 依赖注入方式不符合约定（如字段注入）；数据对象可变导致并发风险；应基础设施化的共性能力被分散实现（多处重复、横向共性需求、新增场景易遗漏调用）；引入与既有实现功能重叠的平行实现（另起一套逻辑），同类能力多套方案并存且无迁移方案；引入或延续可识别技术债且无偿还规划（如采用 EOL/弃用技术选型、临时方案长期固化、接口契约不一致）；重构/变更破坏既有契约（接口/数据/行为）或改变既有行为语义且无兼容说明 | tasks 范围模糊；design 技术细节与 tasks 完成标准不一致 |
+| Low | 数据对象缺少不可变修饰但当前无并发场景；已有代码中违反分层原则但影响极小的结构性缺陷 | 文档引用路径有冗余前缀；描述用词与 spec 不一致但不影响理解 |
+| Info | 建议拆分为独立服务；建议引入某设计模式（仅当不属于 Low 及以上时） | 建议补充某边缘场景说明；可 `（待补充）` 占位、不阻塞开工的边缘信息缺失 |
 
 ### 可维护性维度判例
 
@@ -126,19 +133,19 @@ Info 级别 issue 的 description/suggestion 中禁止出现阶段/时机相关
 
 ### 架构维度
 
-审查时以 design.md 中的架构方案为基线，对照代码验证实施忠实度——代码偏离 design.md 且违反 architecture skill 规范时报 issue。
+架构审查检查点为单一权威清单，两个身份共用同一检查点集，仅视角不同：架构师身份（analyze 阶段）以 design.md 方案文档为审查对象逐项核对方案；quality 架构维度（review 阶段）以实施代码为对象，以 design.md 中的架构方案为基线对照验证实施忠实度——代码偏离 design.md 且违反 architecture skill 规范时报 issue。
 
 - 分层依赖：按 skill 中的架构分层规则和依赖方向
 - 核心层隔离：按 skill 中领域/业务层对框架的依赖限制
 - 依赖注入：按 skill 中的 DI 方式约定（构造器注入 vs 字段注入）
 - 数据对象：按 skill 中的不可变性/可变性约定
 - 端口/适配器模式：按 skill 中的外部依赖契约定义方式
-- 共性能力基础设施化：识别应上收为统一机制的横向逻辑（鉴权/校验/横切约束/重复集成封装等）被多处分散实现的情况——判据为①同一逻辑≥2处重复②属横向共性需求③新增场景漏调用即失效。散落则报 issue。与 maintainability DRY 划界：本维度关注'应单一权威实现的共性能力被分散'，非单纯代码重复。具体上收形式按 skill 约定
+- 共性能力基础设施化：识别应上收为统一机制的横向逻辑（鉴权/校验/横切约束/重复集成封装等）被多处分散实现的情况——判据为①同一逻辑≥2处重复②属横向共性需求③新增场景漏调用即失效。散落则报 issue；方案审查中应上收为统一机制的横向逻辑须在设计中落位。与 maintainability DRY 划界：本维度关注'应单一权威实现的共性能力被分散'，非单纯代码重复。具体上收形式按 skill 约定
 - 接口契约与命名隔离：按 skill 中的外部系统命名隔离约定——外部系统名不得出现在内核与 interfaces 层的接口、方法、DTO 命名中
 - 命名合理性：按 skill 中的通用语言与命名规范——命名体现意图、不与其他场景混淆、与术语表一致防漂移
-- 方案复用与平行实现：识别引入与既有实现功能重叠的平行实现（另起一套逻辑）的情况——同类能力已有既有实现仍另建实现且不改动原实现、无迁移方案则报 issue。与 maintainability DRY 划界：本维度关注技术方案层面的平行引入与迁移缺失，代码级重复归 maintainability。具体复用与迁移要求按 skill 约定
-- 技术债识别：按 skill 中的技术债识别约定——识别实现中的存量与新增技术债（过时技术选型、迁移中断残留、平行实现、临时方案固化、契约不一致），按统一严重级别报 issue
-- 架构演进审查：按 skill 中的架构演进审查约定——实现是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口签名/数据格式/行为语义兼容性）、重构是否贴合项目历史逻辑并保持既有行为语义，破坏兼容或改变既有语义按统一严重级别报 issue；涉及字段/实体承载位置搬迁时，方案须明确数据承接与迁移设计：新承载位置、产出字段写入目标、存量数据迁移、旧位置兼容与清理；缺失按既有契约破坏/重构贴合判例报 issue
+- 方案复用与平行实现：识别引入与既有实现功能重叠的平行实现（另起一套逻辑）的情况——同类能力已有既有实现时须优先复用或扩展，另建实现且不改动原实现、无迁移方案则报 issue；方案确需平行引入（新旧并存）时按需用户拍板问题的确认机制确认并存期与技术债，无人值守缺省裁决为方案必须包含原技术实现的迁移方案。与 maintainability DRY 划界：本维度关注技术方案层面的平行引入与迁移缺失，代码级重复归 maintainability。具体复用与迁移要求按 skill 约定
+- 技术债识别：按 skill 中的技术债识别约定——识别存量与新增技术债（过时技术选型、迁移中断残留、平行实现、临时方案固化、契约不一致），按统一严重级别报 issue；方案引入的债务须在方案中规划偿还或说明可接受理由
+- 架构演进审查：按 skill 中的架构演进审查约定——方案/实现是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口签名/数据格式/行为语义兼容性）、重构是否贴合项目历史逻辑并保持既有行为语义；实施侧破坏兼容或改变既有语义按统一严重级别报 issue，方案侧破坏兼容或偏离架构脉络须在方案中说明理由与过渡安排；涉及字段/实体承载位置搬迁时，方案须明确数据承接与迁移设计：新承载位置、产出字段写入目标、存量数据迁移、旧位置兼容与清理；缺失按既有契约破坏/重构贴合判例报 issue
 
 ### 可维护性维度
 

package/assets/workflows/task-simple.yaml

@@ -77,7 +77,7 @@ phases:
           - "报 issue 时必须显式声明归因维度 dimension（style/architecture/performance/security/maintainability）：本 reviewer 不归属任一质量维度，dimension 即该 issue 归属的目标质量维度"
           - "当发现修复需要调整 openspec/changes/ 下文档时，所报 issue 的 file 字段必须指向目标文档"
           - "报 issue 前先判断该问题能否通过调整确定性质量扫描工具配置（规则收紧/新增规则/配置增强）统一收敛：可工具化 → 双报业务 issue（file=违规现场）与工具改进 issue（file=规则/配置文件，suggestion 含规则草案+验证命令，末尾标 [tool_eligible]，且与业务 issue 同维度），两条 file 不同、方案不同，不构成语义重复，必须双报；工具改进 issue 目标文件在执行边界外时附 boundary_expansion（仅 verdict=failed 时可附）；不可工具化 → 仅报业务 issue。工具化判断细节与规则草案模板遵循已加载的工具改进类 skill，未加载工具改进类 skill 时仅报业务 issue、跳过工具改进环节；提交时在 validation_steps 中记录工具化判断结论"
-          - "默认只报不改：影响代码运行的逻辑类问题只上报、不直接修改；文档/注释等不影响代码运行的问题可直接修改；工具改进建议仅上报（含规则草案），实施由开发者完成"
+          - "只报不改与文档直改：影响代码运行的逻辑类问题只上报、不直接修改；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue，修正情况在提交说明/validation_steps 留痕；工具改进建议仅上报（含规则草案），实施由开发者完成"
           - "复核自己报的已修复待复核（review 态）issue：通过置 done，不通过驳回（附驳回原因，issue 回待修复并累计修复未过次数）"
           - "对视图「待裁定是否可豁免」区块中的豁免申请经 exempt_adjudications 裁定（dismissed/rejected）"
           - "审查变更 diff 与 git log，识别变更中新增的压制手段（压制注解/注释抑制/规则排除配置/平台状态标注/构建跳过开关等）：视为豁免申请，核对 dev 是否已在压制处代码注释或 commit message 说明理由并申报豁免；未申报或理由不成立 → 报 issue（file=压制位置、line=压制行、rule=被压制规则名，severity 至少 Low，description/suggestion 写明判定门槛与理由），要求移除压制真实修复或补申报；理由成立 → 经 exempt_adjudications 裁定 dismissed"
@@ -88,7 +88,7 @@ phases:
           - "提交 opx_agent_submit，必带 verdict、verified_tasks（覆盖全部待验证 task）与 validation_steps（验证步骤执行摘要）"
         constraints:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行确定性工具检查、启动服务并执行验证命令"
-          - "只报不改：禁止 edit/write 影响代码运行的业务代码（逻辑类问题仅上报）；文档/注释等不影响代码运行的内容可直接修改"
+          - "只报不改与文档直改：禁止 edit/write 影响代码运行的内容（逻辑类问题仅上报）；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "即使无 issue / 无待验证 task 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
           - "Info 级 issue 的 description/suggestion 禁止阶段/时机表述（如'可后续处理'）"
           - "禁止以 SonarQube 平台状态修改（SAFE/WONTFIX/False Positive/Confirmed 等）作为豁免手段：平台状态仅作用于当前 SonarQube 项目实例，每次 change 使用独立项目 key，不跨 change 生效；存量问题跨 change 豁免必须经 exempt_issue_ids 申请 → 报源 reviewer 裁定 dismissed 的流程"

package/assets/workflows/task.yaml

@@ -111,7 +111,7 @@ phases:
           - "报静态分析类 issue 时，rule 字段必填官方规则全名（命名格式遵循已加载的质量门类 skill 的规则导航索引），漏填将导致项目级豁免清单无法生效"
           - "报静态分析类 issue 时，description 必须含：①复现命令（非静默形态，含必要开关）；②实测数据（命中类清单/计数）；③规则默认阈值与当前项目配置对比（引用可改的配置文件路径）"
         constraints:
-          - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行工具但不得 edit/write 任何文件"
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行工具；禁止 edit/write 影响代码运行的内容；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "即使无 issue 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
           - "Info 级 issue 的 description/suggestion 禁止阶段/时机表述（如'可后续处理'）"
           - "禁止以 SonarQube 平台状态修改（SAFE/WONTFIX/False Positive/Confirmed 等）作为豁免手段：平台状态仅作用于当前 SonarQube 项目实例，每次 change 使用独立项目 key，不跨 change 生效；存量问题跨 change 豁免必须经 exempt_issue_ids 申请 → 报源 reviewer 裁定 dismissed 的流程"
@@ -137,7 +137,7 @@ phases:
           - "按 opx_status 操作指引完成全部验证项，提交前将每项验证结果与证据填入 validation_steps 参数（未执行的项须填 skip_reason 注明原因），不得省略任何一项"
           - "提交 opx_agent_submit，必带 verdict 与 verified_tasks（覆盖全部待验证 task）"
         constraints:
-          - "工具调用边界：仅可调用 opx_status、opx_agent_submit；可 bash 启动服务/执行检查，但不得 edit/write 业务代码"
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit；可 bash 启动服务/执行检查；禁止 edit/write 影响代码运行的内容；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "即使无 issue / 无待验证 task 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
       - id: verify_quality
         agents:
@@ -164,7 +164,7 @@ phases:
           - "提交 opx_agent_submit，必带 verdict 与 validation_steps（验证步骤执行摘要）"
         constraints:
           - "禁止运行确定性工具检查（包括但不限于 linter/formatter/静态分析/编译/测试/架构约束检查等）；运行权归 tool review 层，本约束不排斥基于已加载 skill 做工具化可行性判断并提交工具改进 issue"
-          - "工具调用边界：仅可调用 opx_status、opx_agent_submit；不得 edit/write 任何文件，仅输出审查报告"
+          - "工具调用边界：仅可调用 opx_status、opx_agent_submit；禁止 edit/write 影响代码运行的内容，仅输出审查报告；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "即使无 issue 也必须提交 verdict=passed；passed=false 时必须有至少一个归属本维度的 Low+ issue 作为理由"
       - id: verify_cleanup
         agents:

package/dsh/cordis.patch.yml

@@ -45,7 +45,7 @@
           - 解锁后第一件事是调用 `mcp__opx__status` 获取上下文，不要先探查仓库或读取状态文件。
 
 
-          OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者与架构师两个逻辑身份）。开发者身份遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug；架构师身份负责文档一致性复核与方案评估。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
+          OpenSpec 编排流程专用 — 开发者（物理 agent，承载开发者逻辑身份）。遵循 TDD 开发新功能，使用 5-Why 分析修复 Bug。仅在 openspec-agents 工作流内由编排者分派使用，不用于通用开发任务。
 
           ## 角色（开发者身份）
 
@@ -64,55 +64,6 @@
           ## 压制处理（开发者身份）
 
           确定性质量工具检查出的问题若以压制手段解决（压制注解、注释抑制、规则排除配置、平台状态标注、构建跳过开关等），属豁免申请范畴：必须在压制处代码注释说明清楚理由（commit message 可补充），交由报源审查者判定合理性；不得以压制手段冒充修复。豁免被驳回后，须移除压制并真实修复。
-
-          ## 角色（架构师身份）
-
-          你是架构师，负责**文档一致性复核与方案评估**：以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题（仅限 md 文件——物理权限为并集 edit: allow，架构师身份的行为边界仍限定仅编辑 md 文档，设计/架构验证问题与信息缺口一律走 blocker），信息齐备时输出执行边界、存在缺口时提交 blockers。
-
-          需用户拍板的问题由你直接确认——blocker 的用户确认环节归属本身份：有人值守时直接向用户确认（question 工具），无人值守时自行裁决。
-
-          ## 严重级别（架构师身份 / 架构维度）
-
-          使用统一严重级别体系（Critical / High / Medium / Low / Info）。
-
-          | 级别 | 本维度典型场景 |
-          |------|--------------------------|
-          | Critical | design 中的 schema 与实现冲突导致无法建表/编译；tasks 缺失核心步骤导致实施方向错误；实施所需关键信息缺失（如模板路径、字段映射未明），导致无法开始实施；**设计架构方案违反 architecture skill 的 MUST 规则** |
-          | High | spec 需求在 tasks 中无对应任务；基础架构任务错排位置；实施所需信息不完整，部分任务需等待补充信息才能推进；**设计方案偏离 architecture skill 推荐做法，存在可通过调整规避的风险** |
-          | High | 设计方案破坏既有接口/数据/行为契约且无兼容或过渡安排；重构方案改变既有行为语义且未显式声明 |
-          | Medium | tasks 范围模糊；design 技术细节与 tasks 完成标准不一致 |
-          | Low | 文档引用路径有冗余前缀；描述用词与 spec 不一致但不影响理解 |
-          | Info | 建议补充某边缘场景说明；可 `（待补充）` 占位、不阻塞开工的边缘信息缺失 |
-
-          ## 审查内容（架构维度）
-
-          与 Review 阶段架构维度 reviewer 共用同一套检查点（锚定同一规范源），审查 design.md 方案时逐项核对：
-
-          - 分层依赖：按 skill 中的架构分层规则和依赖方向
-          - 核心层隔离：按 skill 中领域/业务层对框架的依赖限制
-          - 依赖注入：按 skill 中的 DI 方式约定（构造器注入 vs 字段注入）
-          - 数据对象：按 skill 中的不可变性/可变性约定
-          - 端口/适配器模式：按 skill 中的外部依赖契约定义方式
-          - 共性能力基础设施化：按 skill 中的共性能力基础设施化约定——方案中应上收为统一机制的横向逻辑须在设计中落位
-          - 接口契约与命名隔离：按 skill 中的外部系统命名隔离约定——外部系统名不得出现在内核与 interfaces 层的接口、方法、DTO 命名中
-          - 命名合理性：按 skill 中的通用语言与命名规范——命名体现意图、不与其他场景混淆、与术语表一致防漂移
-          - 方案复用与平行实现：按 skill 中的方案复用与平行实现约定——同类能力已有既有实现时（如已有手工限流基础框架仍引入新限流框架且不改动原实现）须优先复用或扩展，确需平行引入（新旧并存）时按上文需用户拍板问题的确认机制确认并存期与技术债，无人值守缺省裁决为方案必须包含原技术实现的迁移方案
-          - 技术债识别：按 skill 中的技术债识别约定——方案是否引入可识别技术债（过时技术选型、技术迁移中断、平行引入、临时方案固化、契约不一致），引入的债务须在方案中规划偿还或说明可接受理由
-          - 架构演进审查：按 skill 中的架构演进审查约定——方案是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口/数据/行为兼容性）、重构方案是否贴合项目历史逻辑并保持既有行为语义；破坏兼容或偏离架构脉络须在方案中说明理由与过渡安排；涉及字段/实体承载位置搬迁时，方案须明确数据承接与迁移设计：新承载位置、产出字段写入目标、存量数据迁移、旧位置兼容与清理；缺失按既有契约破坏/重构贴合判例报 issue
-
-          ## 执行边界产出（架构师身份）
-
-          `notes` 仅填实施建议，不重复目录/包路径，包含：
-          - 关键坑位提醒（本组特有陷阱，避免重复 AGENTS.md 项目通用坑位）
-          - 组件复用指引（本组范围内可复用的既有实现）
-          - 设计约束的边缘场景说明（design.md 未展开但影响实施的边界条件）
-          - 框架应用说明（如对象映射框架使用要点）
-          - 通用做法指引：识别任务中是否已存在通用做法（如文件类型拦截、权限身份抽取等），有则注明 dev 须遵循现有做法（任务明确要求换做法除外）；无现成但判断应做成通用做法的，注明拓展性要求
-          - 无补充信息时留空（`""`）
-
-          取重责任：**不存在由架构师做语义去重**——issue 去重由 reviewer 自身完成（本维度既有 issue 供 reviewer 参考）。
-
-          行为约束（按评估维度审查、blocker 处理、工具调用边界、只审当前任务组范围）以 opx_status 操作指引与约束区块为准，此处不重复描述。
         enableRunInBackground: false
         backgroundMode: one-shot
     - id: openspec-subagent-reviewer
@@ -135,12 +86,13 @@
           - 解锁后第一件事是调用 `mcp__opx__status` 获取上下文，不要先探查仓库或读取状态文件。
 
 
-          OpenSpec 编排流程专用 — 审核人（物理 agent，承载工具 / 任务 / 5 质量维度 / simple 审查者逻辑身份）。统一只报不改：影响代码运行的逻辑类问题只上报，文档/注释类问题可直接修改。仅在 openspec-agents 工作流内由编排者分派使用。
+          OpenSpec 编排流程专用 — 审核人（物理 agent，承载架构师 + 工具 / 任务 / 5 质量维度 / simple 审查者逻辑身份）。影响代码运行的逻辑类问题只上报；文档/注释类不一致/过时问题直接修正。仅在 openspec-agents 工作流内由编排者分派使用。
 
           ## 角色
 
           你是审核人（Reviewer），承担 OpenSpec 编排流程的审查职责，按分派时的逻辑身份执行对应审查：
 
+          - **架构师**（analyze，方案审查）：文档一致性复核与方案评估——以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题，信息齐备时输出执行边界、存在缺口时提交 blockers
           - **工具维度审查者**（tool review，full 模式三层门禁第一层）：执行确定性工具检查，将工具输出映射为统一 issue 结构；简单（simple）模式亦承担该职责
           - **任务维度审查者**（task review，full 模式三层门禁第二层）：验证 task 产出完整性、启动服务并检查健康、独立执行 API 测试并审查质量、审查测试代码质量；验证完成后清理本变更启动的环境（停止残留服务、清理隔离环境）；简单（simple）模式亦承担该职责
           - **质量维度审查者**（quality review，full 模式三层门禁第三层）：按分派维度（style / architecture / performance / security / maintainability）审查
@@ -150,12 +102,18 @@
 
           复核自己报的已修复（待复核）issue 属本职职责，通过与否由复核结论裁定。
 
-          ## 只报不改
+          ## 角色（架构师身份）
 
-          默认只报不改，适用于全部审查身份（含 full 模式的维度审查）：
+          你是架构师，负责**文档一致性复核与方案评估**：以 design.md 为输入审查架构模式合规性与方案合理性，仅可编辑 md 文档直接修复文档问题（仅限 md 文件——物理权限为并集 edit: allow，架构师身份的行为边界仍限定仅编辑 md 文档，设计/架构验证问题与信息缺口一律走 blocker），信息齐备时输出执行边界、存在缺口时提交 blockers。
+
+          需用户拍板的问题由你直接确认——blocker 的用户确认环节归属本身份：有人值守时直接向用户确认（question 工具），无人值守时自行裁决。
+
+          ## 只报不改与文档直改
+
+          适用于全部审查身份（含架构师身份与 full 模式的维度审查）：
 
           - 影响代码运行的逻辑类问题：只上报 issue，不直接修改相关代码
-          - 文档、注释等不影响代码运行的问题：可直接修改
+          - 文档、注释等不影响代码运行的内容：发现不一致/过时问题时直接修正，不为此报 issue；修正情况在提交说明/validation_steps 留痕
           - 工具改进建议仅上报（含规则草案），实施由开发者完成
 
           ## 严重级别
@@ -196,16 +154,15 @@
 
           ### 架构维度判例
 
-          | 级别 | 本维度典型场景 |
-          |------|--------------|
-          | Critical | 核心层依赖框架导致循环依赖或编译失败 |
-          | High | 表示层直接绕过领域层访问基础设施 |
-          | Medium | 依赖注入方式不符合约定（如字段注入）；数据对象可变导致并发风险；应基础设施化的共性能力被分散实现（多处重复、横向共性需求、新增场景易遗漏调用） |
-          | Medium | 引入与既有实现功能重叠的平行实现（另起一套逻辑），同类能力多套方案并存且无迁移方案 |
-          | Medium | 引入或延续可识别技术债且无偿还规划（如采用 EOL/弃用技术选型、临时方案长期固化、接口契约不一致） |
-          | Medium | 重构/变更破坏既有契约（接口/数据/行为）或改变既有行为语义且无兼容说明 |
-          | Low | 数据对象缺少不可变修饰但当前无并发场景；已有代码中违反分层原则但影响极小的结构性缺陷 |
-          | Info | 建议拆分为独立服务；建议引入某设计模式（仅当不属于 Low 及以上时） |
+          单一权威判例表：架构师身份（审方案文档）与 quality 架构维度（审实施代码）两个视角共用，按所属视角的列取判例。
+
+          | 级别 | 实施代码（quality 架构维度） | 方案文档（架构师身份） |
+          |------|--------------|--------------------------|
+          | Critical | 核心层依赖框架导致循环依赖或编译失败 | design 中的 schema 与实现冲突导致无法建表/编译；tasks 缺失核心步骤导致实施方向错误；实施所需关键信息缺失（如模板路径、字段映射未明），导致无法开始实施；设计架构方案违反 architecture skill 的 MUST 规则 |
+          | High | 表示层直接绕过领域层访问基础设施 | spec 需求在 tasks 中无对应任务；基础架构任务错排位置；实施所需信息不完整，部分任务需等待补充信息才能推进；设计方案偏离 architecture skill 推荐做法，存在可通过调整规避的风险；设计方案破坏既有接口/数据/行为契约且无兼容或过渡安排；重构方案改变既有行为语义且未显式声明 |
+          | Medium | 依赖注入方式不符合约定（如字段注入）；数据对象可变导致并发风险；应基础设施化的共性能力被分散实现（多处重复、横向共性需求、新增场景易遗漏调用）；引入与既有实现功能重叠的平行实现（另起一套逻辑），同类能力多套方案并存且无迁移方案；引入或延续可识别技术债且无偿还规划（如采用 EOL/弃用技术选型、临时方案长期固化、接口契约不一致）；重构/变更破坏既有契约（接口/数据/行为）或改变既有行为语义且无兼容说明 | tasks 范围模糊；design 技术细节与 tasks 完成标准不一致 |
+          | Low | 数据对象缺少不可变修饰但当前无并发场景；已有代码中违反分层原则但影响极小的结构性缺陷 | 文档引用路径有冗余前缀；描述用词与 spec 不一致但不影响理解 |
+          | Info | 建议拆分为独立服务；建议引入某设计模式（仅当不属于 Low 及以上时） | 建议补充某边缘场景说明；可 `（待补充）` 占位、不阻塞开工的边缘信息缺失 |
 
           ### 可维护性维度判例
 
@@ -255,19 +212,19 @@
 
           ### 架构维度
 
-          审查时以 design.md 中的架构方案为基线，对照代码验证实施忠实度——代码偏离 design.md 且违反 architecture skill 规范时报 issue。
+          架构审查检查点为单一权威清单，两个身份共用同一检查点集，仅视角不同：架构师身份（analyze 阶段）以 design.md 方案文档为审查对象逐项核对方案；quality 架构维度（review 阶段）以实施代码为对象，以 design.md 中的架构方案为基线对照验证实施忠实度——代码偏离 design.md 且违反 architecture skill 规范时报 issue。
 
           - 分层依赖：按 skill 中的架构分层规则和依赖方向
           - 核心层隔离：按 skill 中领域/业务层对框架的依赖限制
           - 依赖注入：按 skill 中的 DI 方式约定（构造器注入 vs 字段注入）
           - 数据对象：按 skill 中的不可变性/可变性约定
           - 端口/适配器模式：按 skill 中的外部依赖契约定义方式
-          - 共性能力基础设施化：识别应上收为统一机制的横向逻辑（鉴权/校验/横切约束/重复集成封装等）被多处分散实现的情况——判据为①同一逻辑≥2处重复②属横向共性需求③新增场景漏调用即失效。散落则报 issue。与 maintainability DRY 划界：本维度关注'应单一权威实现的共性能力被分散'，非单纯代码重复。具体上收形式按 skill 约定
+          - 共性能力基础设施化：识别应上收为统一机制的横向逻辑（鉴权/校验/横切约束/重复集成封装等）被多处分散实现的情况——判据为①同一逻辑≥2处重复②属横向共性需求③新增场景漏调用即失效。散落则报 issue；方案审查中应上收为统一机制的横向逻辑须在设计中落位。与 maintainability DRY 划界：本维度关注'应单一权威实现的共性能力被分散'，非单纯代码重复。具体上收形式按 skill 约定
           - 接口契约与命名隔离：按 skill 中的外部系统命名隔离约定——外部系统名不得出现在内核与 interfaces 层的接口、方法、DTO 命名中
           - 命名合理性：按 skill 中的通用语言与命名规范——命名体现意图、不与其他场景混淆、与术语表一致防漂移
-          - 方案复用与平行实现：识别引入与既有实现功能重叠的平行实现（另起一套逻辑）的情况——同类能力已有既有实现仍另建实现且不改动原实现、无迁移方案则报 issue。与 maintainability DRY 划界：本维度关注技术方案层面的平行引入与迁移缺失，代码级重复归 maintainability。具体复用与迁移要求按 skill 约定
-          - 技术债识别：按 skill 中的技术债识别约定——识别实现中的存量与新增技术债（过时技术选型、迁移中断残留、平行实现、临时方案固化、契约不一致），按统一严重级别报 issue
-          - 架构演进审查：按 skill 中的架构演进审查约定——实现是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口签名/数据格式/行为语义兼容性）、重构是否贴合项目历史逻辑并保持既有行为语义，破坏兼容或改变既有语义按统一严重级别报 issue；涉及字段/实体承载位置搬迁时，方案须明确数据承接与迁移设计：新承载位置、产出字段写入目标、存量数据迁移、旧位置兼容与清理；缺失按既有契约破坏/重构贴合判例报 issue
+          - 方案复用与平行实现：识别引入与既有实现功能重叠的平行实现（另起一套逻辑）的情况——同类能力已有既有实现时须优先复用或扩展，另建实现且不改动原实现、无迁移方案则报 issue；方案确需平行引入（新旧并存）时按需用户拍板问题的确认机制确认并存期与技术债，无人值守缺省裁决为方案必须包含原技术实现的迁移方案。与 maintainability DRY 划界：本维度关注技术方案层面的平行引入与迁移缺失，代码级重复归 maintainability。具体复用与迁移要求按 skill 约定
+          - 技术债识别：按 skill 中的技术债识别约定——识别存量与新增技术债（过时技术选型、迁移中断残留、平行实现、临时方案固化、契约不一致），按统一严重级别报 issue；方案引入的债务须在方案中规划偿还或说明可接受理由
+          - 架构演进审查：按 skill 中的架构演进审查约定——方案/实现是否延续项目整体架构方向、是否支持长期迭代演进、是否破坏既有契约（接口签名/数据格式/行为语义兼容性）、重构是否贴合项目历史逻辑并保持既有行为语义；实施侧破坏兼容或改变既有语义按统一严重级别报 issue，方案侧破坏兼容或偏离架构脉络须在方案中说明理由与过渡安排；涉及字段/实体承载位置搬迁时，方案须明确数据承接与迁移设计：新承载位置、产出字段写入目标、存量数据迁移、旧位置兼容与清理；缺失按既有契约破坏/重构贴合判例报 issue
 
           ### 可维护性维度
 

package/package.json

@@ -1,6 +1,13 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.126.0",
+  "version": "0.128.0",
+  "description": "OpenSpec change orchestration plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode)",
+  "author": "ifrankwang",
+  "license": "MIT",
+  "homepage": "https://github.com/ifrankwang/openspec-agents#readme",
+  "bugs": {
+    "url": "https://github.com/ifrankwang/openspec-agents/issues"
+  },
   "type": "module",
   "main": "./src/core/index.ts",
   "exports": {

package/src/adapters/deepseek-harness/index.ts

@@ -25,6 +25,7 @@ import {
   buildAgents,
   buildSkills,
   copyWorkflows,
+  copyLicense,
   readPkgVersion,
   type PluginPackageResult,
 } from "../plugin-common/index.ts"
@@ -32,6 +33,9 @@ import {
 /** DSH bundle 的 npm 包名（与项目发布包一致，便于 `dsh plugin add` 与 sync 识别）。 */
 export const DSH_PLUGIN_NAME = "@ifrankwang/openspec-agents"
 
+/** DSH bundle 包的作者署名（与各插件包 plugin.json 的 author 保持一致）。 */
+export const PLUGIN_AUTHOR_STRING = "ifrankwang"
+
 /** 默认插件包输出目录（dist/ 已 gitignore，生成物不入库）。 */
 export const DEEP_SEEK_HARNESS_PLUGIN_DIR = resolve("dist", "deepseek-harness-plugin")
 /** 简写别名，便于与 `dsh` 缩写保持一致。 */
@@ -87,7 +91,7 @@ function denyEditTools(frontmatter: Record<string, unknown>): boolean {
   if (edit === "deny") return true
   if (edit && typeof edit === "object") {
     const rule = edit as Record<string, unknown>
-    // architect 允许编辑 md，不能整体禁止写工具
+    // edit 规则按通配整体 deny 但对 *.md 单独放行时，不能整体禁止写工具
     return rule["*"] === "deny" && rule["*.md"] !== "allow"
   }
   return false
@@ -174,6 +178,7 @@ export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PL
   const skills = buildSkills(join(outDir, "skills"))
   bundleMcpServer(outDir)
   copyWorkflows(outDir)
+  copyLicense(outDir)
 
   writeFileSync(
     join(outDir, "package.json"),
@@ -184,6 +189,8 @@ export function buildDeepSeekHarnessPlugin(outDir: string = DEEP_SEEK_HARNESS_PL
         description: PLUGIN_DESCRIPTION,
         type: "module",
         private: true,
+        author: PLUGIN_AUTHOR_STRING,
+        license: "MIT",
         dsh: {
           bundle: {
             patch: `./${MANIFEST_PATCH_FILENAME}`,

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

@@ -37,7 +37,7 @@ interface ToolSpec {
 const TOOL_SPECS: Record<string, ToolSpec> = {
   opx_orch_init: {
     description:
-      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式，仅新建状态生效。",
+      "初始化编排会话。传入变更 ID 和任务组 ID，工具自动解析 tasks.md 提取全部任务组并解析目标组子任务。可通过 recovery 参数恢复到指定阶段。无 recovery 重复初始化当前任务组时保留其阶段和进度；切换到其它任务组时初始化该组。可选 mode 参数（full/simple，缺省 simple）选择流程模式：首次新建状态时固化；已开始的变更仅切组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）时可更新，其余场景传不同 mode 报错。",
     schema: orchInitSchema,
     execute: (args, ctx) => initExecute(args as any, ctx),
   },

package/src/adapters/plugin-common/index.ts

@@ -18,9 +18,9 @@ import { parseAgentMd, resolve, EXCLUDED_AGENTS } from "../agent-md.ts"
 
 export const PLUGIN_NAME = "openspec-agents"
 export const PLUGIN_DESCRIPTION =
-  "OpenSpec change 编排：opx_* 编排工具（MCP）+ 编排子代理 + orchestrator skill，非 OpenCode agent 默认无人值守"
-/** plugin.json author（package.json 无 author 字段，取固定值）。 */
-export const PLUGIN_AUTHOR = "openspec-agents maintainers"
+  "OpenSpec change orchestration for AI coding agents: turn OpenSpec change specs into reviewed, high-quality code."
+/** plugin.json author（各插件包统一署名项目作者）。 */
+export const PLUGIN_AUTHOR = "ifrankwang"
 
 export function readPkgVersion(): string {
   return (JSON.parse(readFileSync(resolve("package.json"), "utf-8")) as { version: string }).version
@@ -98,6 +98,14 @@ export function copyWorkflows(targetDir: string): void {
   cpSync(resolve("assets", "workflows"), join(targetDir, "assets", "workflows"), { recursive: true })
 }
 
+/** 复制 MIT 协议文件到插件包根目录（随插件与 marketplace 一起分发）。 */
+export function copyLicense(targetDir: string): void {
+  const license = resolve("LICENSE")
+  if (existsSync(license)) {
+    cpSync(license, join(targetDir, "LICENSE"))
+  }
+}
+
 export interface PluginPackageParams {
   /** 输出目录（如 dist/zcode-plugin/） */
   outDir: string
@@ -129,6 +137,7 @@ export function buildPluginPackage({ outDir, manifestDirName }: PluginPackagePar
   // workflow 定义随包分发：bundle 内 TASK_WORKFLOW_PATH 按部署深度逐级上溯探测
   // assets/workflows/task.yaml，插件根（dist/cache 形态）上溯 1 级即命中
   copyWorkflows(outDir)
+  copyLicense(outDir)
 
   writeFileSync(
     join(outDir, manifestDirName, "plugin.json"),

package/src/core/constants.ts

@@ -33,6 +33,13 @@ export function agentToReviewLayer(agent: string | undefined): ReviewLayer | und
   return undefined
 }
 
+/** reviewer 家族判定（opx_agent_submit 的 worktree 自动提交范围）：openspec-architect +
+ *  全部审查者逻辑身份（openspec-reviewer-tool / -task / 5 个 openspec-reviewer-{dim} /
+ *  simple 合并审查者 openspec-reviewer）。复用 agentToReviewLayer 既有映射推导，勿另立名单。 */
+export function isReviewerFamily(agent: string | undefined): boolean {
+  return agent === "openspec-architect" || agentToReviewLayer(agent) !== undefined
+}
+
 /** 安全读取 issue child 的报源 agent（metadata.source），非 string 返回 undefined。 */
 export function readIssueSource(child: WorkItem): string | undefined {
   return typeof child.metadata["source"] === "string" ? child.metadata["source"] : undefined

package/src/core/git.ts

@@ -371,3 +371,64 @@ export async function reconcileMainPollution(
     }
   }
 }
+
+/** worktree 自动提交（reviewer 家族文档直改兜底）结果。 */
+export interface AutoCommitResult {
+  /** skipped：过滤 openspec/states/ 后无已跟踪文件变更（未触发提交）；committed：add -u + commit 完成；
+   *  failed：git 调用失败（降级返回，不抛异常）。 */
+  status: "skipped" | "committed" | "failed"
+  /** 纳入自动提交的已跟踪文件变更路径（skipped 时为空）。 */
+  files: string[]
+  /** status=failed 时的失败 stderr。 */
+  stderr?: string
+  /** 未跟踪新建文件（?? 条目）路径清单：add -u 不纳入提交，提示编排者另行处理。 */
+  untrackedFiles: string[]
+}
+
+/**
+ * 自动提交 worktree 内已跟踪文件的未提交修改/删除（reviewer 家族文档直改兜底）。
+ *
+ * 触发场景：审查者/架构师按文档直改义务修正文档/注释后，由 opx_agent_submit 在 verdict
+ * 校验通过后调用——未提交修正会被下一轮工具检查点增量检测误判为新变更，也会在
+ * reconcileMainPollution 的干净树预检处死锁，提交时自动 commit 兜底。
+ *
+ * 语义：
+ * 1. `status --porcelain` 解析路径清单，过滤 `openspec/states/` 编排状态目录；过滤后无已跟踪
+ *    文件变更 → skipped（未触发）。
+ * 2. 有变更 → `add -u`（仅已跟踪文件的修改/删除，未跟踪新建文件不纳入，排除 openspec/states/）
+ *    → `commit`（消息风格对齐既有 `docs(tasks):` / `docs(openspec):` 惯例）。
+ * 3. 任一 git 调用失败 → failed（含 stderr），不抛异常——调用方据此在返回体提示，不阻塞 verdict 写入。
+ */
+export async function autoCommitWorktreeChanges(
+  wtPath: string,
+  agent: string,
+  stepId: string,
+): Promise<AutoCommitResult> {
+  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain"])
+  if (!statusRes.success) {
+    return { status: "failed", files: [], untrackedFiles: [], stderr: statusRes.stderr }
+  }
+  const files: string[] = []
+  const untrackedFiles: string[] = []
+  for (const line of statusRes.stdout.split("\n").map((l) => l.trim()).filter(Boolean)) {
+    const path = parsePorcelainPaths(line)[0]
+    if (!path || path.startsWith("openspec/states/")) continue
+    if (line.startsWith("??")) untrackedFiles.push(path)
+    else files.push(path)
+  }
+  if (files.length === 0) return { status: "skipped", files: [], untrackedFiles }
+
+  const addResult = await runGitChecked(wtPath, ["add", "-u", "--", ".", ":(exclude)openspec/states"])
+  if (!addResult.success) {
+    return { status: "failed", files, untrackedFiles, stderr: addResult.stderr }
+  }
+  const commitResult = await runGitChecked(wtPath, [
+    "commit",
+    "-m",
+    `docs(opx): direct fixes by ${agent} (${stepId})`,
+  ])
+  if (!commitResult.success) {
+    return { status: "failed", files, untrackedFiles, stderr: commitResult.stderr }
+  }
+  return { status: "committed", files, untrackedFiles }
+}

package/src/core/state.ts

@@ -271,8 +271,8 @@ export async function readStateByChangeId(worktree: string, changeId: string): P
     createdAt: legacy.createdAt,
     updatedAt: legacy.updatedAt,
     unattended: legacy.unattended,
-    // 透传固化模式：state 已存在（重复初始化/切换任务组/recovery）时沿用既有 mode，
-    // 缺 mode 的旧变更保持缺省（消费端读时兜底 full，不在此写回）
+    // 透传固化模式：读取不改动 mode（缺 mode 的旧变更保持缺省，消费端读时兜底 full，不在此写回）；
+    // init 在允许窗口（切组/重制当前组，其他任务组均终态或从未激活）内可显式更新 state.mode
     mode: legacy.mode,
   }
   if (needsUpgrade) {

package/src/core/tools/lifecycle.ts

@@ -1,5 +1,5 @@
 import path from "path"
-import type { TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
+import type { OrchestrateState, TaskItem, TaskStatus, WorkflowMode } from "../types.ts"
 import { BUILD_PHASE_TARGETS, REVIEW_LAYERS, REVIEW_VERIFY_STEPS } from "../types.ts"
 import { agentToReviewLayer } from "../constants.ts"
 import { runGit, runGitChecked, getCurrentBranch, getMergeBase, isWorktreeClean, markTaskGroupCheckboxesComplete, mergeBranchToTarget, discoverDiskWorktrees, detectMainRepoPollution, detectChanges, type DetectChangesResult } from "../git.ts"
@@ -278,6 +278,25 @@ function assertValidRecovery(recovery: InitParams["recovery"]): void {
   }
 }
 
+/**
+ * 判断目标组以外的全部任务组（workItems 中 `task:` 前缀、非目标组）是否"终态或从未激活"，
+ * 即 mode 切换窗口（W1 切组 / W2 重制当前组）的共同前置条件：
+ * - 终态：item.phase === "done" 或 metadata.completed_at 已设置；
+ * - 从未激活：无执行痕迹——tags 为空且所有 task children 的 phase 均为 todo 或终态（isTerminalPhase）。
+ */
+function otherTaskGroupsSettled(state: OrchestrateState, targetGroupId: string): boolean {
+  return state.workItems
+    .filter((w) => w.id.startsWith("task:") && w.id !== `task:${targetGroupId}`)
+    .every((item) => {
+      if (item.phase === "done" || item.metadata["completed_at"] !== undefined) return true
+      const noTags = Object.keys(item.tags).length === 0
+      const childrenSettled = item.children
+        .filter((c) => c.type === "task")
+        .every((c) => c.phase === "todo" || isTerminalPhase(c.phase))
+      return noTags && childrenSettled
+    })
+}
+
 export async function initExecute(params: InitParams, ctx: ToolContext): Promise<string> {
   assertOrchestrator(ctx, "opx_orch_init")
 
@@ -326,6 +345,31 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
   let state = await readStateByChangeId(ctx.worktree, args.change_id)
   const wasCurrentGroup = state?.taskGroupId === args.task_group_id
 
+  // state 已存在时的 mode 变更窗口校验/更新（位于 for 循环前——循环内非活跃组新建 item 与
+  // applyRecoveryState 均读 state.mode；错误早于任何状态变更抛出，不落盘）：
+  // - 无变更意图（不传 mode 或与生效值一致——旧 state 缺 mode 时生效值兜底 full）→ 放行，保持既有行为；
+  // - W1 切组：task_group_id ≠ state.taskGroupId 且其他任务组均终态或从未激活；
+  // - W2 重制当前组：recovery.phase=task_analysis 且其他任务组均终态或从未激活
+  //   （reopenIssues 仅支持 dev_impl，与 W2 天然互斥，不构成冲突路径）；
+  // - 窗口外传不同 mode → 报错。
+  let modeSwitchNote: string | null = null
+  if (state && args.mode !== undefined && args.mode !== (state.mode ?? "full")) {
+    const othersSettled = otherTaskGroupsSettled(state, args.task_group_id)
+    const withinWindow =
+      ((args.task_group_id !== state.taskGroupId || args.recovery?.phase === "task_analysis") && othersSettled)
+    if (!withinWindow) {
+      throw new Error(
+        `mode 参数与已固化的流程模式不一致：已固化 mode="${state.mode ?? "full"}"${state.mode === undefined ? "（旧变更未固化，读取时兜底 full）" : ""}，传入值："${args.mode}"。\n` +
+        `当前场景不允许切换流程模式：切换任务组须其他任务组均已完成或从未激活；重制当前组仅支持 recovery.phase="task_analysis"（其他任务组同样须已完成或从未激活）。\n` +
+        `请去掉 mode 参数继续沿用固化模式，或满足上述窗口条件后再切换。`
+      )
+    }
+    const prevMode = state.mode
+    state.mode = args.mode
+    // 旧变更未固化 mode 时读取兜底 full，切换说明按 full 表述
+    modeSwitchNote = `流程模式已从 ${prevMode ?? "full"} 切换为 ${args.mode}。`
+  }
+
   if (!state) {
     state = {
       changeId: args.change_id,
@@ -335,8 +379,8 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
       workItems: [],
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString(),
-      // 新建 state 时固化模式：取 init 参数 mode（缺省 simple）；state 已存在不读参数，
-      // 沿用 state 既有 mode；旧 state 缺 mode 由消费端读时兜底 full，不写回。
+      // 新建 state 时固化模式：取 init 参数 mode（缺省 simple）；state 已存在时的 mode 变更
+      // 由上方窗口校验统一处理（W1 切组 / W2 重制当前组），旧 state 缺 mode 由消费端读时兜底 full，不写回。
       mode: args.mode ?? "simple",
     }
   } else {
@@ -443,9 +487,10 @@ export async function initExecute(params: InitParams, ctx: ToolContext): Promise
   state.taskGroupId = args.task_group_id
   await writeState(ctx.worktree, state)
 
-  return args.recovery
-    ? `编排会话已初始化。已恢复到 ${args.recovery.phase} 阶段。`
-    : "编排会话已初始化。"
+  const parts = ["编排会话已初始化。"]
+  if (args.recovery) parts.push(`已恢复到 ${args.recovery.phase} 阶段。`)
+  if (modeSwitchNote) parts.push(modeSwitchNote)
+  return parts.join("")
 }
 
 async function bindWorktreeRefs(

package/src/core/tools/schemas.ts

@@ -217,7 +217,7 @@ export const orchInitSchema: JSONSchema = {
       type: "string",
       enum: ["full", "simple"],
       description:
-        "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。仅新建编排状态（首次 opx_orch_init）时生效；已开始的变更沿用固化模式，不支持中途切换。",
+        "流程模式选择：full=完整流程（analyze→implement→三重审查+收尾验证）；simple=精简流程（implement→quality_review→done，缺省）。首次新建编排状态时固化；已开始的变更仅在允许窗口内可更新：切换任务组（其他任务组均已完成或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）；其余场景传不同 mode 将报错。",
     },
   },
   required: ["change_id", "task_group_id"],

package/src/core/tools/submit.ts

@@ -11,11 +11,11 @@ import {
   getStepVerdict, clearStepTags, isBlockingSeverity, isInfoSeverity, isTerminalPhase, applyTransition,
 } from "../workflow/engine.ts"
 import { resetReviewTagsOnFix, dedupeNewChildren, resolveChildIssueFields } from "../workflow/reset.ts"
-import { agentToReviewDimension, agentToReviewLayer, readIssueSource } from "../constants.ts"
+import { agentToReviewDimension, agentToReviewLayer, isReviewerFamily, readIssueSource } from "../constants.ts"
 import { REVIEW_DIMENSIONS } from "../types.ts"
 import type { Dimension } from "../types.ts"
 import { taskChildrenOf, taskChildById, normalizeTaskChildIds, taskListOf, issueChildrenOf } from "../task-children.ts"
-import { reconcileMainPollution, getCurrentHead, isWorktreeClean } from "../git.ts"
+import { autoCommitWorktreeChanges, reconcileMainPollution, getCurrentHead, isWorktreeClean } from "../git.ts"
 import { assertIssueFilesWithin } from "../paths.ts"
 import {
   readStateByWorktree, writeState, getLockPath, acquireLock, releaseLock,
@@ -734,6 +734,33 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
       newChildren: accepted,
     })
 
+    // reviewer 家族（openspec-architect + 全部审查者逻辑身份）worktree 直改修正自动提交兜底：
+    // 审查者/架构师按文档直改义务修正文档/注释后，提交时自动 commit（openspec/states/ 编排状态
+    // 除外，仅纳入已跟踪文件的修改/删除）。
+    // 时序硬约束：必须在 _tool_review_checkpoint 捕获之前（否则修正会被下一轮增量检测误判为新
+    // 变更）、必须在 reconcileMainPollution 之前（其干净树预检要求 worktree 无未提交内容——架构师
+    // 身份的 worktree md 修正无人提交会在该预检处死锁）。
+    // 硬边界（防事故）：自动提交目标恒为 wtPath（任务组 worktree），严禁对 ctx.worktree（主仓库）
+    // 执行 add/commit。失败不阻塞 verdict 写入，仅在返回体提示编排者安排补提交。
+    const autoCommitLines: string[] = []
+    if (isReviewerFamily(ctx.agent)) {
+      const ac = await autoCommitWorktreeChanges(wtPath, ctx.agent, params.step_id)
+      if (ac.status === "committed") {
+        autoCommitLines.push(
+          `- ✅ worktree 直改修正已自动提交（${ac.files.length} 个文件，commit message: \`docs(opx): direct fixes by ${ctx.agent} (${params.step_id})\`）`,
+        )
+      } else if (ac.status === "failed") {
+        autoCommitLines.push(
+          `- ⚠️ worktree 直改修正自动提交失败：${ac.stderr || "未知错误"}。请编排者安排补提交（worktree 内 git add -u 后 commit）`,
+        )
+      }
+      if (ac.untrackedFiles.length > 0) {
+        autoCommitLines.push(
+          `- ⚠️ 存在未跟踪新建文件未纳入自动提交（须纳入版本控制时由编排者/开发者处理）：${ac.untrackedFiles.join("、")}`,
+        )
+      }
+    }
+
     // arch_submit 主仓库污染文档自动合并兜底（56ddfe9 意图）：analyze step（架构师）以 passed 提交后，
     // 若主仓库本 change 目录下存在未提交 openspec 文档污染，并入 worktree 分支并清理主仓库工作树。
     if (
@@ -766,7 +793,15 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
     }
 
     await writeState(ctx.worktree, state)
-    return SUBMIT_OK_MESSAGE
+    if (autoCommitLines.length === 0) return SUBMIT_OK_MESSAGE
+    return [
+      `## ✅ ${SUBMIT_OK_MESSAGE}`,
+      "",
+      "### worktree 自动提交",
+      "",
+      ...autoCommitLines,
+      "",
+    ].join("\n")
   } finally {
     releaseLock(lockPath)
   }

package/src/core/tools/types.ts

@@ -28,7 +28,9 @@ export interface InitParams {
      *  恢复后 currentStep 落在第一个未全部通过的 verify step，可能早于被重置的 step。 */
     reset_steps?: ReviewVerifyStep[]
   }
-  /** 流程模式（full/simple），仅新建编排状态时生效；已开始的变更沿用固化模式，不支持中途切换。 */
+  /** 流程模式（full/simple）：首次新建编排状态时固化；已开始的变更仅在切组（其他任务组均已完成
+   *  或从未激活）或 recovery.phase=task_analysis 重制当前组（其他任务组同样须已完成或从未激活）
+   *  时允许更新，窗口外传不同 mode 报错。 */
   mode?: WorkflowMode
 }
 

package/src/core/types.ts

@@ -136,6 +136,8 @@ export interface OrchestrateState {
   updatedAt: string
   unattended?: boolean
   /** 变更开始时固化的流程模式（经 opx_orch_init 的 mode 参数写入，缺省 simple）。
-   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 不再被参数改动覆盖。 */
+   *  缺失即旧变更，一律按 full 处理（读时兜底，不写回）；已存在的 state 仅在 init 允许窗口
+   *  （切组且其他任务组均已完成或从未激活，或 recovery.phase=task_analysis 重制当前组）内
+   *  可被 mode 参数更新。 */
   mode?: WorkflowMode
 }