@ifrankwang/openspec-agents 0.127.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";
@@ -36581,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, {
@@ -36597,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);
   }
@@ -37127,7 +37185,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.127.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/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,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.127.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",

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

@@ -91,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

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/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)
   }