@ifrankwang/openspec-agents 0.151.0 → 0.151.1

package/.dsh-plugin/opx-tools.mjs

@@ -205,6 +205,31 @@ async function isWorktreeClean(worktree) {
   const out = await runGit(worktree, ["status", "--porcelain"]);
   return out.length === 0;
 }
+function isDocLikePath(p) {
+  return p.startsWith("openspec/") || /\.md$/i.test(p);
+}
+async function listDirtyNonDocFiles(worktree) {
+  const res = await runGitChecked(worktree, ["status", "--porcelain", "-uall"]);
+  if (!res.success)
+    return [];
+  const seen = new Set;
+  const files = [];
+  for (const entry of parseStatusEntries(res.stdout)) {
+    for (const p of entry.paths) {
+      if (!p)
+        continue;
+      if (p.startsWith("openspec/states/"))
+        continue;
+      if (isDocLikePath(p))
+        continue;
+      if (seen.has(p))
+        continue;
+      seen.add(p);
+      files.push(p);
+    }
+  }
+  return files;
+}
 async function markTaskGroupCheckboxesComplete(worktree, changeId, taskGroupId) {
   const tasksMdPath = path.join(worktree, "openspec", "changes", changeId, "tasks.md");
   let content;
@@ -615,27 +640,48 @@ async function reconcileMainPollution(mainRepo, worktreePath, opts) {
   }
 }
 async function autoCommitWorktreeChanges(wtPath, agent, stepId) {
-  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain"]);
+  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain", "-uall"]);
   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/"))
+  const trackedFiles = [];
+  const untrackedDocFiles = [];
+  const untrackedOtherFiles = [];
+  const seen = new Set;
+  const pushUnique = (list, path2) => {
+    if (seen.has(path2))
+      return;
+    seen.add(path2);
+    list.push(path2);
+  };
+  for (const entry of parseStatusEntries(statusRes.stdout)) {
+    const isUntracked = entry.x === "?" && entry.y === "?";
+    if (isUntracked) {
+      for (const path2 of entry.paths) {
+        if (!path2 || path2.startsWith("openspec/states/"))
+          continue;
+        pushUnique(isDocLikePath(path2) ? untrackedDocFiles : untrackedOtherFiles, path2);
+      }
       continue;
-    if (line.startsWith("??"))
-      untrackedFiles.push(path2);
-    else
-      files.push(path2);
+    }
+    const newPath = entry.paths[entry.paths.length - 1];
+    if (!newPath || newPath.startsWith("openspec/states/"))
+      continue;
+    pushUnique(trackedFiles, newPath);
   }
-  if (files.length === 0)
-    return { status: "skipped", files: [], untrackedFiles };
+  if (trackedFiles.length === 0 && untrackedDocFiles.length === 0) {
+    return { status: "skipped", files: [], untrackedFiles: untrackedOtherFiles };
+  }
+  const committedFiles = [...trackedFiles, ...untrackedDocFiles];
   const addResult = await runGitChecked(wtPath, ["add", "-u", "--", ".", ":(exclude)openspec/states"]);
   if (!addResult.success) {
-    return { status: "failed", files, untrackedFiles, stderr: addResult.stderr };
+    return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: addResult.stderr };
+  }
+  if (untrackedDocFiles.length > 0) {
+    const addDocResult = await runGitChecked(wtPath, ["add", "--", ...untrackedDocFiles]);
+    if (!addDocResult.success) {
+      return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: addDocResult.stderr };
+    }
   }
   const commitResult = await runGitChecked(wtPath, [
     "commit",
@@ -643,9 +689,9 @@ async function autoCommitWorktreeChanges(wtPath, agent, stepId) {
     `docs(opx): direct fixes by ${agent} (${stepId})`
   ]);
   if (!commitResult.success) {
-    return { status: "failed", files, untrackedFiles, stderr: commitResult.stderr };
+    return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: commitResult.stderr };
   }
-  return { status: "committed", files, untrackedFiles };
+  return { status: "committed", files: committedFiles, untrackedFiles: untrackedOtherFiles };
 }
 
 // src/core/state.ts
@@ -8327,6 +8373,22 @@ async function agentSubmitExecute(params, ctx) {
     }
     const newChildren = (params.new_children ?? []).map((nc) => buildIssueChild(nc, ctx.agent));
     if (stepPhase === "review") {
+      if (isReviewerFamily(ctx.agent)) {
+        const dirtyNonDoc = await listDirtyNonDocFiles(wtPath);
+        if (dirtyNonDoc.length > 0) {
+          const fileLines = dirtyNonDoc.map((f) => `  - ${f}`).join(`
+`);
+          throw new Error(`提交被拒绝：工作区存在未提交的代码类改动。
+` + `可能是反向探针改坏的实现未还原，或违反了「只报不改」直接修改了代码。
+` + `涉及文件：
+${fileLines}
+` + `请先清理后再提交：
+` + `  - 已跟踪文件的改动：git checkout -- <文件> 还原
+` + `  - 新增的临时文件：直接删除
+` + `文档类改动（openspec/ 下文件与 .md 文件）不受此限，提交时会自动 commit；
+` + `确属必要的代码修正，请自行 commit 后再提交。`);
+        }
+      }
       const stepCfg = workflow.stepMap.get(params.step_id).step;
       const agentCfg = stepCfg.agents.find((a) => a.id === ctx.agent);
       handleReviewParams(item, params, newChildren, params.step_id, {
@@ -8336,11 +8398,12 @@ async function agentSubmitExecute(params, ctx) {
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params);
     } else if (stepPhase === "in_progress") {
-      if (state.mode === "simple" && params.step_id === "implement") {
+      if (params.step_id === "implement" && (state.mode === "simple" || params.verdict === "passed")) {
         const clean = await isWorktreeClean(wtPath);
         if (!clean) {
-          throw new Error(`simple 模式 implement 提交被拒绝：工作区存在未提交内容。
-请先 git commit 提交全部变更后再提交 implement。`);
+          throw new Error(state.mode === "simple" ? `simple 模式 implement 提交被拒绝：工作区存在未提交内容。
+请先 git commit 提交全部变更后再提交 implement。` : `full 模式 implement 提交被拒绝：工作区存在未提交内容。
+请先 git commit 后再提交 implement。`);
         }
       }
       handleImplementParams(item, params);
@@ -8370,10 +8433,10 @@ async function agentSubmitExecute(params, ctx) {
       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）`);
+        autoCommitLines.push(`- ⚠️ worktree 直改修正自动提交失败：${ac.stderr || "未知错误"}。请编排者安排补提交（在 worktree 内手工 add 并 commit：已跟踪改动用 git add -u，未跟踪文档用 git add -- <文件>）`);
       }
       if (ac.untrackedFiles.length > 0) {
-        autoCommitLines.push(`- ⚠️ 存在未跟踪新建文件未纳入自动提交（须纳入版本控制时由编排者/开发者处理）：${ac.untrackedFiles.join("、")}`);
+        autoCommitLines.push(`- ⚠️ 存在未跟踪的非文档类文件未纳入自动提交（文档类已自动提交；这些须由编排者/开发者自行处理）：${ac.untrackedFiles.join("、")}`);
       }
     }
     if (stepPhase === "todo" && params.step_id === "analyze" && params.verdict === "passed" && wtPath && typeof item.metadata["branch_name"] === "string") {

package/.mcp-server/cli.mjs

@@ -21856,6 +21856,31 @@ async function isWorktreeClean(worktree) {
   const out = await runGit(worktree, ["status", "--porcelain"]);
   return out.length === 0;
 }
+function isDocLikePath(p) {
+  return p.startsWith("openspec/") || /\.md$/i.test(p);
+}
+async function listDirtyNonDocFiles(worktree) {
+  const res = await runGitChecked(worktree, ["status", "--porcelain", "-uall"]);
+  if (!res.success)
+    return [];
+  const seen = new Set;
+  const files = [];
+  for (const entry of parseStatusEntries(res.stdout)) {
+    for (const p of entry.paths) {
+      if (!p)
+        continue;
+      if (p.startsWith("openspec/states/"))
+        continue;
+      if (isDocLikePath(p))
+        continue;
+      if (seen.has(p))
+        continue;
+      seen.add(p);
+      files.push(p);
+    }
+  }
+  return files;
+}
 async function markTaskGroupCheckboxesComplete(worktree, changeId, taskGroupId) {
   const tasksMdPath = path.join(worktree, "openspec", "changes", changeId, "tasks.md");
   let content;
@@ -22266,27 +22291,48 @@ async function reconcileMainPollution(mainRepo, worktreePath, opts) {
   }
 }
 async function autoCommitWorktreeChanges(wtPath, agent, stepId) {
-  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain"]);
+  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain", "-uall"]);
   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/"))
+  const trackedFiles = [];
+  const untrackedDocFiles = [];
+  const untrackedOtherFiles = [];
+  const seen = new Set;
+  const pushUnique = (list, path2) => {
+    if (seen.has(path2))
+      return;
+    seen.add(path2);
+    list.push(path2);
+  };
+  for (const entry of parseStatusEntries(statusRes.stdout)) {
+    const isUntracked = entry.x === "?" && entry.y === "?";
+    if (isUntracked) {
+      for (const path2 of entry.paths) {
+        if (!path2 || path2.startsWith("openspec/states/"))
+          continue;
+        pushUnique(isDocLikePath(path2) ? untrackedDocFiles : untrackedOtherFiles, path2);
+      }
       continue;
-    if (line.startsWith("??"))
-      untrackedFiles.push(path2);
-    else
-      files.push(path2);
+    }
+    const newPath = entry.paths[entry.paths.length - 1];
+    if (!newPath || newPath.startsWith("openspec/states/"))
+      continue;
+    pushUnique(trackedFiles, newPath);
   }
-  if (files.length === 0)
-    return { status: "skipped", files: [], untrackedFiles };
+  if (trackedFiles.length === 0 && untrackedDocFiles.length === 0) {
+    return { status: "skipped", files: [], untrackedFiles: untrackedOtherFiles };
+  }
+  const committedFiles = [...trackedFiles, ...untrackedDocFiles];
   const addResult = await runGitChecked(wtPath, ["add", "-u", "--", ".", ":(exclude)openspec/states"]);
   if (!addResult.success) {
-    return { status: "failed", files, untrackedFiles, stderr: addResult.stderr };
+    return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: addResult.stderr };
+  }
+  if (untrackedDocFiles.length > 0) {
+    const addDocResult = await runGitChecked(wtPath, ["add", "--", ...untrackedDocFiles]);
+    if (!addDocResult.success) {
+      return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: addDocResult.stderr };
+    }
   }
   const commitResult = await runGitChecked(wtPath, [
     "commit",
@@ -22294,9 +22340,9 @@ async function autoCommitWorktreeChanges(wtPath, agent, stepId) {
     `docs(opx): direct fixes by ${agent} (${stepId})`
   ]);
   if (!commitResult.success) {
-    return { status: "failed", files, untrackedFiles, stderr: commitResult.stderr };
+    return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: commitResult.stderr };
   }
-  return { status: "committed", files, untrackedFiles };
+  return { status: "committed", files: committedFiles, untrackedFiles: untrackedOtherFiles };
 }
 
 // src/core/state.ts
@@ -29978,6 +30024,22 @@ async function agentSubmitExecute(params, ctx) {
     }
     const newChildren = (params.new_children ?? []).map((nc) => buildIssueChild(nc, ctx.agent));
     if (stepPhase === "review") {
+      if (isReviewerFamily(ctx.agent)) {
+        const dirtyNonDoc = await listDirtyNonDocFiles(wtPath);
+        if (dirtyNonDoc.length > 0) {
+          const fileLines = dirtyNonDoc.map((f) => `  - ${f}`).join(`
+`);
+          throw new Error(`提交被拒绝：工作区存在未提交的代码类改动。
+` + `可能是反向探针改坏的实现未还原，或违反了「只报不改」直接修改了代码。
+` + `涉及文件：
+${fileLines}
+` + `请先清理后再提交：
+` + `  - 已跟踪文件的改动：git checkout -- <文件> 还原
+` + `  - 新增的临时文件：直接删除
+` + `文档类改动（openspec/ 下文件与 .md 文件）不受此限，提交时会自动 commit；
+` + `确属必要的代码修正，请自行 commit 后再提交。`);
+        }
+      }
       const stepCfg = workflow.stepMap.get(params.step_id).step;
       const agentCfg = stepCfg.agents.find((a) => a.id === ctx.agent);
       handleReviewParams(item, params, newChildren, params.step_id, {
@@ -29987,11 +30049,12 @@ async function agentSubmitExecute(params, ctx) {
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params);
     } else if (stepPhase === "in_progress") {
-      if (state.mode === "simple" && params.step_id === "implement") {
+      if (params.step_id === "implement" && (state.mode === "simple" || params.verdict === "passed")) {
         const clean = await isWorktreeClean(wtPath);
         if (!clean) {
-          throw new Error(`simple 模式 implement 提交被拒绝：工作区存在未提交内容。
-请先 git commit 提交全部变更后再提交 implement。`);
+          throw new Error(state.mode === "simple" ? `simple 模式 implement 提交被拒绝：工作区存在未提交内容。
+请先 git commit 提交全部变更后再提交 implement。` : `full 模式 implement 提交被拒绝：工作区存在未提交内容。
+请先 git commit 后再提交 implement。`);
         }
       }
       handleImplementParams(item, params);
@@ -30021,10 +30084,10 @@ async function agentSubmitExecute(params, ctx) {
       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）`);
+        autoCommitLines.push(`- ⚠️ worktree 直改修正自动提交失败：${ac.stderr || "未知错误"}。请编排者安排补提交（在 worktree 内手工 add 并 commit：已跟踪改动用 git add -u，未跟踪文档用 git add -- <文件>）`);
       }
       if (ac.untrackedFiles.length > 0) {
-        autoCommitLines.push(`- ⚠️ 存在未跟踪新建文件未纳入自动提交（须纳入版本控制时由编排者/开发者处理）：${ac.untrackedFiles.join("、")}`);
+        autoCommitLines.push(`- ⚠️ 存在未跟踪的非文档类文件未纳入自动提交（文档类已自动提交；这些须由编排者/开发者自行处理）：${ac.untrackedFiles.join("、")}`);
       }
     }
     if (stepPhase === "todo" && params.step_id === "analyze" && params.verdict === "passed" && wtPath && typeof item.metadata["branch_name"] === "string") {
@@ -30629,7 +30692,7 @@ async function ensureDefaultUnattended(args, ctx) {
     }
   } catch {}
 }
-var PKG_VERSION = "0.151.0";
+var PKG_VERSION = "0.151.1";
 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-reviewer.md

@@ -34,7 +34,7 @@ permission:
 适用于全部审查身份（含架构师身份与 full 模式的维度审查）：
 
 - 影响代码运行的逻辑类问题：只上报 issue，不直接修改相关代码
-- 反向探针例外：仅任务验证与合并审查身份可用——核验测试对抗力时可临时改坏被测实现，动作固定为四步：改坏被测实现 → 确认对应用例变红 → 原样还原实现 → 全量用例复跑全绿；探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动），探针内容禁止提交，不得保留任何痕迹
+- 反向探针例外：仅任务验证与合并审查身份可用——核验测试对抗力时可临时改坏被测实现，动作固定为四步：改坏被测实现 → 确认对应用例变红 → 原样还原实现 → 全量用例复跑全绿；探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动），探针内容禁止提交，不得保留任何痕迹；残留的代码类未提交改动会被工具层拒绝提交，文档类修正（含新建的 openspec/ 与 .md 文件）照常自动提交；源码文件内的注释修正请自行 commit 后再提交，仅 openspec/ 与 .md 文件由工具自动提交
 - 文档、注释等不影响代码运行的内容：发现不一致/过时问题时直接修正，不为此报 issue；修正情况在提交说明/validation_steps 留痕
 - 工具改进建议仅上报（含规则草案），实施由开发者完成
 

package/assets/workflows/review-simple.yaml

@@ -83,6 +83,7 @@ phases:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行确定性工具检查、启动服务并执行验证命令"
           - "只报不改与文档直改：禁止 edit/write 影响代码运行的内容（逻辑类问题仅上报）；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "反向探针例外：执行反向探针核验时可临时改坏被测实现（仅限探针所需的最小改动），探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动）、全量用例复跑全绿；探针内容禁止提交，不得保留任何痕迹；用例未变红视为该用例无对抗力，须报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 issue 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
           - "Info 级 issue 的 description/suggestion 禁止阶段/时机表述（如'可后续处理'）"
           - "压制类 issue 严重级别至少 Low"

package/assets/workflows/review.yaml

@@ -41,7 +41,7 @@ phases:
           - "以视图 Issue 清单驱动修复：Low+ 必办（修复后经 fixed_issue_ids 上报进入待复核），Info 建议修复不阻塞提交；不可修 issue 经 exempt_issue_ids 申请豁免（申请后进入待裁定状态，由报源 reviewer 裁定，被驳回的 issue 回待修复）；全部 blocking issue 均已上报修复或申请豁免后才可 passed 提交推进"
           - "执行边界缺省整个 worktree（独立审查无分析环节，不生成边界白名单）；issue 的 file 字段指向的文件即修复边界，修复这些文件（含回归引入问题）不算越界；可按 issue 的 suggestion 直接执行修复；reviewer 的 boundary_expansion 已并入边界"
           - "对修复未过次数≥2 的 issue 须先完成 5-Why 根因分析再动手，不得跳过分析直接改代码"
-          - "修复完成后先 git commit 再提交；提交前按已加载的质量门类 skill 完成本地构建验证，并按维度规范类 skill（style/architecture/performance/security/maintainability 能力类别）对本次修复文件逐项自检，自检结论与工具检查结果一并汇总进 self_check_results"
+          - "修复完成后先 git commit 再提交（未提交内容会被工具拒绝）；提交前按已加载的质量门类 skill 完成本地构建验证，并按维度规范类 skill（style/architecture/performance/security/maintainability 能力类别）对本次修复文件逐项自检，自检结论与工具检查结果一并汇总进 self_check_results"
           - "自证/验证需启动服务或基础设施时，一律按已加载技术栈 skill 的隔离启动规范以隔离方式启动，隔离标识与建议端口以视图 Worktree 区块为准；验证完成后停止本次启动的实例，不留残留，残留判定遵循已加载清理规范的归属判别，无法确认归属本变更的进程一律不清；禁止为腾出端口或资源而停止、复用或干扰非本会话启动的进程"
           - "确定性质量工具检查出的问题不得以压制手段（压制注解/注释抑制/规则排除配置/平台状态标注/构建跳过开关等）静默规避：确需压制时，必须在压制处代码注释说明清楚理由，并经 exempt_issue_ids 申请豁免由报源 reviewer 裁定；不得以 fixed_issue_ids 冒充修复"
           - "提交 opx_agent_submit：必传 verdict；修复完成的 issue 经 fixed_issue_ids 上报、不可修 issue 经 exempt_issue_ids 申请豁免"
@@ -73,6 +73,7 @@ phases:
           - "报静态分析类 issue 时，description 必须含：①复现命令（非静默形态，含必要开关）；②实测数据（命中类清单/计数）；③规则默认阈值与当前项目配置对比（引用可改的配置文件路径）"
         constraints:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行工具；禁止 edit/write 影响代码运行的内容；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 issue 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
           - "Info 级 issue 的 description/suggestion 禁止阶段/时机表述（如'可后续处理'）"
           - "压制类 issue 严重级别至少 Low"
@@ -97,6 +98,7 @@ phases:
         constraints:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit；可 bash 启动服务/执行检查；禁止 edit/write 影响代码运行的内容；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "反向探针例外：执行反向探针核验时可临时改坏被测实现（仅限探针所需的最小改动），探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动）、全量用例复跑全绿；探针内容禁止提交，不得保留任何痕迹；用例未变红视为该用例无对抗力，须报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 issue 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
           - "禁止为腾出端口或资源而停止、复用或干扰非本会话启动的进程（含用户或其他会话运行的服务实例）；验证所需环境一律按隔离标识隔离启动"
       - id: verify_quality
@@ -124,4 +126,5 @@ phases:
         constraints:
           - "禁止运行确定性工具检查（包括但不限于 linter/formatter/静态分析/编译/测试/架构约束检查等）；运行权归工具检查层，本约束不排斥基于已加载 skill 做工具化可行性判断并提交工具改进 issue"
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit；禁止 edit/write 影响代码运行的内容，仅输出审查报告；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 issue 也必须提交 verdict=passed；passed=false 时必须有至少一个归属本维度的 Low+ issue 作为理由"

package/assets/workflows/task-simple.yaml

@@ -97,6 +97,7 @@ phases:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行确定性工具检查、启动服务并执行验证命令"
           - "只报不改与文档直改：禁止 edit/write 影响代码运行的内容（逻辑类问题仅上报）；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "反向探针例外：执行反向探针核验时可临时改坏被测实现（仅限探针所需的最小改动），探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动）、全量用例复跑全绿；探针内容禁止提交，不得保留任何痕迹；用例未变红视为该用例无对抗力，须报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 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

@@ -70,7 +70,7 @@ phases:
           - "issue 指向文件的目录已并入执行边界，修复这些文件（含回归引入问题）不算越界；issue 的 file 字段指向 openspec/changes/ 下文档时，按该 issue 要求修复对应文档同样不算越界（仅限该 issue 指定文件，不得扩大范围）；可按 issue 的 suggestion 直接执行修复；reviewer 的 boundary_expansion 已并入边界"
           - "按视图 Issue 清单分类实施：Low+ 必办，Info 建议修复不阻塞提交"
           - "对修复未过次数≥2 的 issue 须先完成 5-Why 根因分析再动手，不得跳过分析直接改代码"
-          - "全部实现完成后先 git commit 再提交"
+          - "全部实现完成后先 git commit 再提交（未提交内容会被工具拒绝）"
           - "提交前按已加载的质量门类 skill 完成本地构建验证并核对覆盖率门禁达标后再提交"
           - "提交前完成自检并经 self_check_results 汇总"
           - "提交前按已加载的维度规范类 skill（style/architecture/performance/security/maintainability 能力类别）对本次变更文件逐项自检（聚焦本轮变更文件，不扩散全量代码），自检结论与工具检查结果一并汇总进 self_check_results；修复被驳回 issue 后再次提交前同样须按维度规范类 skill 对变更文件自检后再提交"
@@ -115,6 +115,7 @@ phases:
           - "报静态分析类 issue 时，description 必须含：①复现命令（非静默形态，含必要开关）；②实测数据（命中类清单/计数）；③规则默认阈值与当前项目配置对比（引用可改的配置文件路径）"
         constraints:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit、question（需要用户协助处理时）；可 bash 运行工具；禁止 edit/write 影响代码运行的内容；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 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 的流程"
@@ -146,6 +147,7 @@ phases:
         constraints:
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit；可 bash 启动服务/执行检查；禁止 edit/write 影响代码运行的内容；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
           - "反向探针例外：执行反向探针核验时可临时改坏被测实现（仅限探针所需的最小改动），探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动）、全量用例复跑全绿；探针内容禁止提交，不得保留任何痕迹；用例未变红视为该用例无对抗力，须报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 issue / 无待验证 task 也必须提交 verdict=passed（不通过必须有至少一个 Low+ issue 作为理由）"
       - id: verify_quality
         agents:
@@ -173,6 +175,7 @@ phases:
         constraints:
           - "禁止运行确定性工具检查（包括但不限于 linter/formatter/静态分析/编译/测试/架构约束检查等）；运行权归 tool review 层，本约束不排斥基于已加载 skill 做工具化可行性判断并提交工具改进 issue"
           - "工具调用边界：仅可调用 opx_status、opx_agent_submit；禁止 edit/write 影响代码运行的内容，仅输出审查报告；文档/注释等不影响代码运行的内容发现不一致/过时问题时直接修正，不为此报 issue"
+          - "提交前工作区不得残留代码类未提交改动（反向探针改动必须还原、新增临时文件必须删除）；文档类改动（openspec/ 下文件与 .md 文件，含新建的未跟踪文件）会在提交时自动 commit，不受此限。工具层会拒绝带代码类未提交改动的提交"
           - "即使无 issue 也必须提交 verdict=passed；passed=false 时必须有至少一个归属本维度的 Low+ issue 作为理由"
       - id: verify_cleanup
         agents:

package/dsh/cordis.patch.yml

@@ -158,7 +158,7 @@
                 适用于全部审查身份（含架构师身份与 full 模式的维度审查）：
 
                 - 影响代码运行的逻辑类问题：只上报 issue，不直接修改相关代码
-                - 反向探针例外：仅任务验证与合并审查身份可用——核验测试对抗力时可临时改坏被测实现，动作固定为四步：改坏被测实现 → 确认对应用例变红 → 原样还原实现 → 全量用例复跑全绿；探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动），探针内容禁止提交，不得保留任何痕迹
+                - 反向探针例外：仅任务验证与合并审查身份可用——核验测试对抗力时可临时改坏被测实现，动作固定为四步：改坏被测实现 → 确认对应用例变红 → 原样还原实现 → 全量用例复跑全绿；探针结束后必须原样还原并确认 git 工作区无残留改动（git status 无改动），探针内容禁止提交，不得保留任何痕迹；残留的代码类未提交改动会被工具层拒绝提交，文档类修正（含新建的 openspec/ 与 .md 文件）照常自动提交；源码文件内的注释修正请自行 commit 后再提交，仅 openspec/ 与 .md 文件由工具自动提交
                 - 文档、注释等不影响代码运行的内容：发现不一致/过时问题时直接修正，不为此报 issue；修正情况在提交说明/validation_steps 留痕
                 - 工具改进建议仅上报（含规则草案），实施由开发者完成
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ifrankwang/openspec-agents",
-  "version": "0.151.0",
+  "version": "0.151.1",
   "description": "OpenSpec companion plugin for AI coding agents (Claude Code, Codex, ZCode, DeepSeek Harness, OpenCode): a stricter proposal standard plus multi-agent implementation and review, gated to production-grade standards",
   "author": "ifrankwang",
   "license": "MIT",

package/src/core/git.ts

@@ -219,6 +219,47 @@ export async function isWorktreeClean(worktree: string): Promise<boolean> {
   return out.length === 0
 }
 
+/**
+ * 文档类路径判定：`openspec/` 下文件与 `.md` 后缀文件属文档类（reviewer 直改自动提交的白名单）。
+ * 源码、配置、脚本等其余路径一律不算文档类。
+ */
+export function isDocLikePath(p: string): boolean {
+  return p.startsWith("openspec/") || /\.md$/i.test(p)
+}
+
+/**
+ * 列出 worktree 中「非文档类」的未提交改动文件（已跟踪修改/删除 + 未跟踪新文件）。
+ *
+ * 用途：reviewer 家族提交前的机制层预检——反向探针改坏的实现若未还原，其改动会被自动 commit
+ * 静默吞掉。过滤 `openspec/states/`（编排状态文件）与文档类，其余一律视为需要清理的代码类改动；
+ * 结果去重并保持 `git status --porcelain` 的出现顺序。
+ *
+ * status 查询失败时返回空数组，属 fail-open 降级：读不到工作区状态不阻断审查提交
+ * （与 runGit 失败返回空串的既有降级口径一致），不要误认为是 bug。
+ */
+export async function listDirtyNonDocFiles(worktree: string): Promise<string[]> {
+  // 用 -uall 让未跟踪目录展开成具体文件：默认 porcelain 会把新建目录折叠成 `?? docs/`，
+  // 目录路径既不是 openspec/ 前缀也不以 .md 结尾，会让「新目录里只放了 .md」被误判为代码类。
+  const res = await runGitChecked(worktree, ["status", "--porcelain", "-uall"])
+  if (!res.success) return []
+  const seen = new Set<string>()
+  const files: string[] = []
+  // 用 parseStatusEntries 而非 parsePorcelainPaths：rename 条目（`R  old -> new`）必须双向解析。
+  // 只取新路径会漏判「代码文件改名为 .md」——旧路径的代码删除被当成文档改动放行，删除会被自动
+  // commit 静默吞掉。任一方向路径非文档类即视为需清理的代码类改动。
+  for (const entry of parseStatusEntries(res.stdout)) {
+    for (const p of entry.paths) {
+      if (!p) continue
+      if (p.startsWith("openspec/states/")) continue
+      if (isDocLikePath(p)) continue
+      if (seen.has(p)) continue
+      seen.add(p)
+      files.push(p)
+    }
+  }
+  return files
+}
+
 export async function markTaskGroupCheckboxesComplete(
   worktree: string,
   changeId: string,
@@ -771,53 +812,83 @@ export async function reconcileMainPollution(
 
 /** worktree 自动提交（reviewer 家族文档直改兜底）结果。 */
 export interface AutoCommitResult {
-  /** skipped：过滤 openspec/states/ 后无已跟踪文件变更（未触发提交）；committed：add -u + commit 完成；
-   *  failed：git 调用失败（降级返回，不抛异常）。 */
+  /** skipped：过滤 openspec/states/ 后既无已跟踪文件变更、也无未跟踪文档类（未触发提交）；
+   *  committed：add -u + 未跟踪文档类的 git add + commit 完成；failed：git 调用失败（降级返回，不抛异常）。 */
   status: "skipped" | "committed" | "failed"
-  /** 纳入自动提交的已跟踪文件变更路径（skipped 时为空）。 */
+  /** 本次实际提交的文件路径（已跟踪变更 + 未跟踪文档类）。rename 条目只保留新路径，
+   *  避免同一重命名被计成两个文件；旧路径不丢信息——重命名前路径的删除已由提交前预检拦截。 */
   files: string[]
   /** status=failed 时的失败 stderr。 */
   stderr?: string
-  /** 未跟踪新建文件（?? 条目）路径清单：add -u 不纳入提交，提示编排者另行处理。 */
+  /** 未纳入自动提交的未跟踪文件（?? 条目）路径清单：非文档类，提示编排者/开发者另行处理。
+   *  未跟踪的文档类文件已纳入自动提交，不出现在此清单。 */
   untrackedFiles: string[]
 }
 
 /**
- * 自动提交 worktree 内已跟踪文件的未提交修改/删除（reviewer 家族文档直改兜底）。
+ * 自动提交 worktree 内的文档类改动（reviewer 家族文档直改兜底）。
  *
- * 触发场景：审查者/架构师按文档直改义务修正文档/注释后，由 opx_agent_submit 在 verdict
- * 校验通过后调用——未提交修正会被下一轮工具检查点增量检测误判为新变更，也会在
- * reconcileMainPollution 的干净树预检处死锁，提交时自动 commit 兜底。
+ * 触发场景：审查者/架构师按文档直改义务修正文档后，由 opx_agent_submit 在 verdict 校验通过后
+ * 调用——未提交修正会被下一轮工具检查点增量检测误判为新变更，也会在 reconcileMainPollution 的
+ * 干净树预检处死锁，提交时自动 commit 兜底。
  *
  * 语义：
- * 1. `status --porcelain` 解析路径清单，过滤 `openspec/states/` 编排状态目录；过滤后无已跟踪
- *    文件变更 → skipped（未触发）。
- * 2. 有变更 → `add -u`（仅已跟踪文件的修改/删除，未跟踪新建文件不纳入，排除 openspec/states/）
+ * 1. `status --porcelain` 解析条目（rename 双向解析），过滤 `openspec/states/` 编排状态目录；
+ *    文档类（openspec/ 与 .md）中的已跟踪改动与未跟踪新建文件都纳入提交，其余未跟踪文件
+ *    （非文档类）不纳入、经 untrackedFiles 提示调用方处理。
+ * 2. 过滤后既无已跟踪变更、也无未跟踪文档类 → skipped（不产生空 commit）。
+ * 3. 有可提交内容 → `add -u`（已跟踪修改/删除，排除 openspec/states/）+ `add -- <未跟踪文档>`
  *    → `commit`（消息风格对齐既有 `docs(tasks):` / `docs(openspec):` 惯例）。
- * 3. 任一 git 调用失败 → failed（含 stderr），不抛异常——调用方据此在返回体提示，不阻塞 verdict 写入。
+ * 4. 任一 git 调用失败 → failed（含 stderr），不抛异常——调用方据此在返回体提示，不阻塞 verdict 写入。
  */
 export async function autoCommitWorktreeChanges(
   wtPath: string,
   agent: string,
   stepId: string,
 ): Promise<AutoCommitResult> {
-  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain"])
+  // -uall：未跟踪目录展开为具体文件，避免新建目录里的文档类文件被折叠成目录路径而判成非文档类。
+  const statusRes = await runGitChecked(wtPath, ["status", "--porcelain", "-uall"])
   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)
+  const trackedFiles: string[] = []
+  const untrackedDocFiles: string[] = []
+  const untrackedOtherFiles: string[] = []
+  const seen = new Set<string>()
+  const pushUnique = (list: string[], path: string): void => {
+    if (seen.has(path)) return
+    seen.add(path)
+    list.push(path)
+  }
+  for (const entry of parseStatusEntries(statusRes.stdout)) {
+    const isUntracked = entry.x === "?" && entry.y === "?"
+    if (isUntracked) {
+      for (const path of entry.paths) {
+        if (!path || path.startsWith("openspec/states/")) continue
+        pushUnique(isDocLikePath(path) ? untrackedDocFiles : untrackedOtherFiles, path)
+      }
+      continue
+    }
+    // 已跟踪条目：rename（`R  old -> new`）只记新路径，避免同一重命名在提示里计成两个文件。
+    // 旧路径不丢信息：重命名前路径的删除已由提交前预检拦截（走不到这里的自动提交阶段）。
+    const newPath = entry.paths[entry.paths.length - 1]
+    if (!newPath || newPath.startsWith("openspec/states/")) continue
+    pushUnique(trackedFiles, newPath)
+  }
+  if (trackedFiles.length === 0 && untrackedDocFiles.length === 0) {
+    return { status: "skipped", files: [], untrackedFiles: untrackedOtherFiles }
   }
-  if (files.length === 0) return { status: "skipped", files: [], untrackedFiles }
 
+  const committedFiles = [...trackedFiles, ...untrackedDocFiles]
   const addResult = await runGitChecked(wtPath, ["add", "-u", "--", ".", ":(exclude)openspec/states"])
   if (!addResult.success) {
-    return { status: "failed", files, untrackedFiles, stderr: addResult.stderr }
+    return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: addResult.stderr }
+  }
+  if (untrackedDocFiles.length > 0) {
+    const addDocResult = await runGitChecked(wtPath, ["add", "--", ...untrackedDocFiles])
+    if (!addDocResult.success) {
+      return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: addDocResult.stderr }
+    }
   }
   const commitResult = await runGitChecked(wtPath, [
     "commit",
@@ -825,7 +896,7 @@ export async function autoCommitWorktreeChanges(
     `docs(opx): direct fixes by ${agent} (${stepId})`,
   ])
   if (!commitResult.success) {
-    return { status: "failed", files, untrackedFiles, stderr: commitResult.stderr }
+    return { status: "failed", files: committedFiles, untrackedFiles: untrackedOtherFiles, stderr: commitResult.stderr }
   }
-  return { status: "committed", files, untrackedFiles }
+  return { status: "committed", files: committedFiles, untrackedFiles: untrackedOtherFiles }
 }

package/src/core/tools/submit.ts

@@ -15,7 +15,7 @@ import { agentToReviewDimension, agentToReviewLayer, isReviewerFamily, readIssue
 import { REVIEW_DIMENSIONS } from "../types.ts"
 import type { Dimension } from "../types.ts"
 import { taskChildrenOf, taskChildById, normalizeTaskChildIds, taskListOf, issueChildrenOf } from "../task-children.ts"
-import { autoCommitWorktreeChanges, reconcileMainPollution, getCurrentHead, isWorktreeClean } from "../git.ts"
+import { autoCommitWorktreeChanges, listDirtyNonDocFiles, reconcileMainPollution, getCurrentHead, isWorktreeClean } from "../git.ts"
 import { assertIssueFilesWithin } from "../paths.ts"
 import {
   readStateByWorktree, writeState, getLockPath, acquireLock, releaseLock,
@@ -792,6 +792,28 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
     const newChildren = (params.new_children ?? []).map((nc) => buildIssueChild(nc, ctx.agent))
 
     if (stepPhase === "review") {
+      // 机制层预检：工作区不得残留「非文档类」未提交改动。reviewer 家族提交后会对 wtPath 自动
+      // commit 工作区改动（见下方 isReviewerFamily 分支），反向探针改坏的实现若未还原会被静默
+      // 提交掉；这里在一切参数处理与状态写入之前拦截，拒绝时零状态变更（与 simple implement
+      // 检查同守则）。failed 提交同样拦截——failed 也会触发自动 commit，不拦会把探针残留提交掉。
+      // 文档类（openspec/ 与 .md）放行，由自动 commit 兜底；verify_cleanup 是 developer 身份，
+      // 非 reviewer 家族，不经此预检。
+      if (isReviewerFamily(ctx.agent)) {
+        const dirtyNonDoc = await listDirtyNonDocFiles(wtPath)
+        if (dirtyNonDoc.length > 0) {
+          const fileLines = dirtyNonDoc.map((f) => `  - ${f}`).join("\n")
+          throw new Error(
+            `提交被拒绝：工作区存在未提交的代码类改动。\n` +
+            `可能是反向探针改坏的实现未还原，或违反了「只报不改」直接修改了代码。\n` +
+            `涉及文件：\n${fileLines}\n` +
+            `请先清理后再提交：\n` +
+            `  - 已跟踪文件的改动：git checkout -- <文件> 还原\n` +
+            `  - 新增的临时文件：直接删除\n` +
+            `文档类改动（openspec/ 下文件与 .md 文件）不受此限，提交时会自动 commit；\n` +
+            `确属必要的代码修正，请自行 commit 后再提交。`,
+          )
+        }
+      }
       // 必做清单覆盖度门禁取「当前提交 agent 的能力集」：各 agent 只按自身 capability_tags 解析 skill。
       // verify_quality 多 agent 各自解析不出声明 must_do 的 skill（自动跳过），verify_tool 按 quality-gate
       // 能力集、verify_task 按 test-design 能力集分别校验各自的必做清单。
@@ -810,15 +832,21 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
     } else if (stepPhase === "todo") {
       handleAnalyzeParams(item, params)
     } else if (stepPhase === "in_progress") {
-      // simple 模式 implement 提交强检查（2.2）：工作区必须无未提交内容，不干净直接拒绝并提示先 commit。
-      // simple 无 analyze 环节、执行边界默认整个 worktree，dev 提交即收尾合并的载体，未提交内容会
-      // 让收尾裸合并携带脏状态；检查在一切参数处理与状态写入之前，拒绝时零状态变更（含内存态）。
-      // 收尾门禁（completeTaskGroupExecute 的 worktree 干净检查）仍原样保留作最终兜底。
-      if (state.mode === "simple" && params.step_id === "implement") {
+      // implement 提交工作区干净校验：工作区必须无未提交内容，不干净直接拒绝并提示先 commit。
+      // 两种模式口径不同：
+      // - simple：无 analyze 环节、执行边界默认整个 worktree，dev 提交即收尾合并的载体，未提交内容
+      //   会让收尾裸合并携带脏状态——无条件检查（含 verdict=failed）。
+      // - full：仅 verdict=passed 时检查。failed 提交多为 blocker/需求缺口上报，此时半成品脏工作区
+      //   属正常，强查会把 dev 报 blocker 的路径堵死。
+      // 检查在一切参数处理与状态写入之前，拒绝时零状态变更（含内存态）；收尾门禁
+      // （completeTaskGroupExecute 的 worktree 干净检查）仍原样保留作最终兜底。
+      if (params.step_id === "implement" && (state.mode === "simple" || params.verdict === "passed")) {
         const clean = await isWorktreeClean(wtPath)
         if (!clean) {
           throw new Error(
-            "simple 模式 implement 提交被拒绝：工作区存在未提交内容。\n请先 git commit 提交全部变更后再提交 implement。"
+            state.mode === "simple"
+              ? "simple 模式 implement 提交被拒绝：工作区存在未提交内容。\n请先 git commit 提交全部变更后再提交 implement。"
+              : "full 模式 implement 提交被拒绝：工作区存在未提交内容。\n请先 git commit 后再提交 implement。"
           )
         }
       }
@@ -875,12 +903,12 @@ export async function agentSubmitExecute(params: AgentSubmitParams, ctx: ToolCon
         )
       } else if (ac.status === "failed") {
         autoCommitLines.push(
-          `- ⚠️ worktree 直改修正自动提交失败：${ac.stderr || "未知错误"}。请编排者安排补提交（worktree 内 git add -u 后 commit）`,
+          `- ⚠️ worktree 直改修正自动提交失败：${ac.stderr || "未知错误"}。请编排者安排补提交（在 worktree 内手工 add 并 commit：已跟踪改动用 git add -u，未跟踪文档用 git add -- <文件>）`,
         )
       }
       if (ac.untrackedFiles.length > 0) {
         autoCommitLines.push(
-          `- ⚠️ 存在未跟踪新建文件未纳入自动提交（须纳入版本控制时由编排者/开发者处理）：${ac.untrackedFiles.join("、")}`,
+          `- ⚠️ 存在未跟踪的非文档类文件未纳入自动提交（文档类已自动提交；这些须由编排者/开发者自行处理）：${ac.untrackedFiles.join("、")}`,
         )
       }
     }