hunter-harness 0.1.3 → 0.2.0

package/resources/harness/bundles/java/claude-code/harness-submit/checklist.md

@@ -0,0 +1,407 @@
+---
+description: harness-submit 的8 步工作流详细步骤和执行日志记录格式。仅在执行提交流程时读取。
+---
+
+# harness-submit 检查清单
+
+## P0 提交稳定性门禁（先读）
+
+执行任何 commit 前必须遵循 `reference.md` 与 `../protocols/submit-protocol.md`：
+
+- 提交方式只用固定三选项：commit+push / 仅本地 commit / 取消。
+- commit message 必须写入 `.harness/changes/<change>/runtime/commit-message.txt`。
+- 使用 `git commit -F`，禁止先英文 commit 再 amend。
+- commit message 禁止 `Co-Authored-By`、`Generated by`、`AI generated`。
+- AskUserQuestion 参数错误时不得自行绕过，必须改用固定模板重问。
+- staged diff 是唯一提交依据。
+
+
+## 步骤 0：启动准备
+
+确定变更名：用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。默认最多一个未归档变更；如有多个，优先取最近修改的，或询问用户。
+
+**读取 worktree.json 判定模式**：读取 `.harness/changes/<change-name>/meta/worktree.json`。`requested=true` → **worktree 模式**：submit 只本地 commit、不 push，commit 成功后**自动接续** checklist「worktree 合并流程」步骤 M0–M8（`/harness-merge` 为别名，可从 M0 重入）。`requested=false` → 主目录模式：正常 commit+push 主分支。
+
+**读取 verification-ledger + post-test 变更分类**：
+
+1. 读取 `.harness/changes/<change-name>/evidence/verification-ledger.json`，记录 `diffHash` / `currentHead` / `unitTest` / `apiTest` 状态
+2. 计算当前 diff 的 diffHash，与 ledger 比对
+3. 若 test 之后有代码变更（当前 diffHash ≠ test 完成时的 diffHash），按 7 类对 post-test diff 分类（见 `../protocols/ledger-protocol.md` 第六章），写入 ledger 的 `postTestClassification`
+4. 行为性变更（BEHAVIORAL_SERVICE_CHANGE / API_CONTRACT_CHANGE / SQL_OR_MAPPER_CHANGE / SECURITY_OR_PERMISSION_CHANGE）→ **停止 submit**，提示先重跑 `/harness-test` 相关场景
+5. 非行为性变更（NON_BEHAVIORAL_CLEANUP / COMMENT_ONLY / TEST_ONLY）→ 可继续 submit，但后续验证按复用规则处理
+
+**append `phase.start` 事件**（`harness_events.py append`；`note` 含 ledger diffHash、post-test 分类、验证策略）：
+
+## 步骤 1：合并最新代码
+
+> **分支名自动读取**：不硬编码 `master` 或 `main`，使用 `git rev-parse --abbrev-ref @{u}` 自动读取 upstream 分支。
+
+```powershell
+# 0. 自动读取 upstream
+powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref @{u}"
+
+# 1. 暂存当前变更
+powershell.exe -Command "git -C '<项目路径>' stash"
+
+# 2. 拉取并合并远程
+powershell.exe -Command "git -C '<项目路径>' pull --rebase"
+
+# 3. 恢复暂存的变更
+powershell.exe -Command "git -C '<项目路径>' stash pop"
+```
+
+**Shell 安全规则（强制）**：
+- 任何 git 命令被 hook 拒绝（`Denied` / `PreToolUse:Bash hook error`）→ 停止流程，不得宣称"拉取成功"
+- 拉取成功的判断证据：git 输出包含 `Already up to date.` 或 `Fast-forward`、`Updating <hash>..<hash>`，且 exit code 为 0
+
+如果 stash pop 冲突或 merge 冲突，参考 `reference.md` 的常见问题处理。
+
+## 步骤 2：最终验证（ledger 复用优先）
+
+**先判断是否可复用 test 阶段验证**。读取 ledger 后，若**全部满足**：
+
+- 当前 diffHash 与 ledger 一致（或 post-test 仅为非行为性清理）
+- `unitTest.status=OK` 且 `apiTest.status=OK`
+- postTestClassification ∈ {NON_BEHAVIORAL_CLEANUP, COMMENT_ONLY, TEST_ONLY, 无}
+- 远端无新提交（步骤 1 pull 未引入他人提交）
+- 用户未要求 `submit-full-verify`
+
+→ **跳过重跑** 项目构建/测试命令，复用 ledger 结果，在执行日志标记 `🔁REUSED`，并在提交摘要写明"验证复用 test 阶段结果（diffHash=<...>）"。
+
+**重跑触发条件**（任一满足则必须重跑）：
+
+- 远端有新提交并完成 pull/rebase
+- staged diff 与 ledger diffHash 不一致且属行为性变更
+- post-test 修改属于行为性变更（已在步骤 0 拦截，此处兜底）
+- test 报告缺失或失败
+- 用户要求 `submit-full-verify`
+
+重跑时只使用 harness-submit 自有确定性验证，不调用 Superpowers 合并/收尾流程：
+
+```powershell
+powershell.exe -NoProfile -Command "<项目构建命令>"
+powershell.exe -NoProfile -Command "<项目测试命令>"
+```
+
+> **接口测试依赖编译产物时的重跑顺序**（通用）：若项目的接口测试执行器（如 in-process HTTP server runner）import 编译产物（build output）而非源码，重跑接口测试前**必须先跑构建命令**重新编译，否则接口测试测的是 post-test 改动前的旧产物，会漏检行为性变更。单元测试若通过别名/直指源码则不受影响，但接口测试执行器通常依赖独立编译产物——务必先编译再跑接口测试。
+
+编译或测试失败 → 停止提交，提示用户修复。
+
+**重跑后必须把结果写回 ledger** 的 `compile`/`unitTest` 项，并更新 `diffHash`/`currentHead`。
+
+**提交前最终门禁**（步骤 2 末尾，commit 前强制，`unitTestFull` 模块级全量）：
+
+```powershell
+python <skills-root>/scripts/harness_ledger.py can-reuse `
+  --change-dir ".harness/changes/<change-name>" `
+  --verification unitTestFull --scope module `
+  --project . --profile-input unitTestFull `
+  --command "<build-profile.json buildCommands.unitTestFull>" --json
+```
+
+- `--profile-input unitTestFull` 从 `build-profile.json` 的 `verificationInputs.unitTestFull` 展开**依赖闭包**文件集，**禁止用仅含 staged 业务文件的 `--files` 快捷方式**冒充全量闭包。
+- `--command` 必须直接读取当前项目 `build-profile.json` 的 `buildCommands.unitTestFull`，禁止原样复制示例模块名。
+- 增量 `unitTest`（scope=测试类）永远不能冒充 `unitTestFull` 门禁；ledger 只有 `unitTest` 时返回 `insufficient-evidence`。
+- `reuse=false` → 执行 `buildCommands.unitTestFull`（模块级全量单元测试），成功后用**同一文件集、command、`scope=module`** 写回 ledger 的 `unitTestFull` 项，再继续步骤 3。
+- profile 缺 `verificationInputs.unitTestFull` / glob 无匹配 / 结果为空 → 返回 `insufficient-evidence`（exit 0），仍须执行全量测试但**不允许缓存复用**，直到 profile 正确配置。
+
+**编译/测试成功必须有明确证据**：
+- 构建命令输出必须包含构建成功证据（如 `BUILD SUCCESS` / `Finished` / exit code 0）
+- 测试命令输出必须包含测试通过证据（如 `Tests run: N, Failures: 0` / `passed` / exit code 0）
+- 命令被 hook 拒绝或 exit code 非 0 → 标记为 ❌ 失败，停止提交流程
+
+**review 报告**（参考性）：如果 `.harness/changes/<change-name>/reports/review/review-report-*.md` 存在（旧路径 `reviews/` 兼容），可读取并展示摘要（如“review 报告：RED 高风险建议 N 个，YELLOW 中低风险建议 M 个，仅供参考”），但不得因 review 结果阻塞提交。
+
+**review fixback**（参考性）：如果 `.harness/changes/<change-name>/reports/review/fixback-*.md` 存在，展示最新 fixback 摘要并提示“可回到 `/harness-run --fixback` 处理”；除非 `review.strict-review-gate=true` 且存在 RED，否则不得阻塞提交。
+
+## 步骤 3：.gitignore 检查 + 暂存业务文件 ⚠️ 强制阻断
+
+提交前**强制检查 `.gitignore`** 是否包含 `.harness/`：
+
+```powershell
+powershell.exe -Command "Select-String -Path '<项目路径>\.gitignore' -Pattern '\.harness'"
+```
+
+如果未包含：
+- **必须提醒用户**：`⚠️ .gitignore 未包含 .harness/，会导致 .harness/ 下文件被提交（含日志、报告、可能含敏感信息）`
+- **默认不提交 .harness/ 下文件**：使用 AskUserQuestion 询问用户是否：
+  1. 添加 .harness/ 到 .gitignore（推荐）
+  2. 仅 stage 业务代码文件，不提交 .harness/
+  3. 取消提交
+
+**git status 中如出现 .harness/changes/**：
+```powershell
+powershell.exe -Command "git -C '<项目路径>' status --porcelain | Select-String '\.harness'"
+```
+- 如果有匹配，必须只 stage 业务代码文件，**禁止 `git add -A`**
+- 推荐 stage 方式：明确列出业务代码文件路径 `git add <file1> <file2> ...`
+
+## 步骤 4：提交方式选择（固定三选项）
+
+**worktree 模式（requested=true）**：固定为「仅本地 commit」，不展示「commit+push」选项；commit 完成后继续下方「worktree 合并流程」，跳过下方三选项询问。
+
+`harness-submit` 不调用 Superpowers 呈现合并选项。只允许使用固定 AskUserQuestion 模板：
+
+```text
+本次变更已完成验证，请选择提交方式：
+
+1. commit + push 到当前 upstream
+2. 仅本地 commit，不 push
+3. 取消提交
+```
+
+禁止在此步骤引入“创建 PR”“丢弃所有变更”“直接合并到主分支”等旧选项，避免 AskUserQuestion 参数错误和流程歧义。
+
+## 步骤 5：展示提交摘要 + 确认 ⚠️ 强制阻断
+
+展示完整的 commit message 和变更列表，等待用户确认。**不可跳过此步。**
+
+**commit message 生成规则**：
+- subject 只根据 `git diff --cached` 当前实际暂存的变更，或本次变更名生成
+- **不得混入历史任务上下文**（如之前的 plan 描述、与本次 diff 无关的短语）
+- 示例：本次 indicator 权限修复，正确 subject 应类似 `fix(indicator): 修复指标库列表组织权限过滤`，不得出现与本次 diff 无关的内容
+
+**展示四项信息**（缺一不可）：
+
+```powershell
+# 1. 实际 staged 文件列表
+powershell.exe -Command "git -C '<项目路径>' diff --cached --name-only"
+
+# 2. diff stat
+powershell.exe -Command "git -C '<项目路径>' diff --cached --stat"
+```
+
+格式：
+
+```markdown
+## 准备提交
+
+### 1. 实际 Staged 文件列表
+（基于 git diff --cached --name-only 的实际输出）
+- src/.../业务代码文件
+- test/.../测试代码文件
+
+### 2. Diff Stat
+ src/.../业务代码文件 | +12 -3
+ test/.../测试代码文件 | +45 -0
+ 2 files changed, 57 insertions(+), 3 deletions(-)
+
+### 3. Commit Message
+<type>(<scope>): <中文描述>
+
+- 变更点1
+- 变更点2
+
+### 4. 是否会 push
+（根据本步骤提交方式选择：会推送到 origin/<branch> / 仅本地提交，不推送）
+
+### 确认？
+回复「是」→ 执行提交 | 回复「改」→ 修改 message | 回复「取消」→ 放弃
+```
+
+> Git 提交信息**不包含** `Co-Authored-By` 行（遵循项目 git-commit.md 规范）。
+
+
+### 5.1 生成 commit-message.txt（强制）
+
+在用户确认前，必须把完整中文 commit message 写入：
+
+```text
+.harness/changes/<change-name>/runtime/commit-message.txt
+```
+
+用 Write 工具或 PowerShell 创建文件。message 不得包含 `Co-Authored-By`、`Generated by`、`AI generated`。
+
+用户确认时展示该文件完整内容；确认后步骤 6 必须使用：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' commit -F '.harness/changes/<change-name>/runtime/commit-message.txt'"
+```
+
+不得使用 `git commit -m` 提交长中文 message，不得先提交英文再 amend。
+
+## 步骤 6：执行 commit 和可选 push
+
+**worktree 模式（requested=true）**：只执行下方 `git commit -F`，**不执行 push**；记录 local commit hash 后**继续 worktree 合并流程 M0**，不结束 submit。
+
+用户确认后，根据步骤 4 的提交方式选择执行：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' commit -F '.harness/changes/<change-name>/runtime/commit-message.txt'"
+```
+
+**记录 pre-pull local commit hash**：
+```powershell
+powershell.exe -Command "git -C '<项目路径>' rev-parse HEAD"
+```
+保存为 `<pre-pull-hash>` 用于后续比对。
+
+**push 前的远程新提交检查（强制）**：
+
+```powershell
+# 拉取远程最新引用
+powershell.exe -Command "git -C '<项目路径>' fetch"
+
+# 检查远程是否有新提交（自上次 fetch 以来）
+powershell.exe -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+```
+
+**如果远程有新提交**（输出非空）：
+- **不得直接 pull 后 push**
+- 必须 pull/rebase 后**重新构建/测试**（ledger 复用条件被破坏，须重跑并写回 ledger）
+- 验证通过后再 push
+- 使用 AskUserQuestion 询问用户：
+  ```
+  远程有新提交（N 个），需要 pull/rebase 后重新验证：
+  1. 重新验证（pull/rebase + 构建 + 测试）
+  2. 停止 push（保留本地提交，等待用户后续处理）
+  ```
+- 如果用户选 2，必须停止 push，不得强行推送
+
+**如果远程无新提交**（输出为空），可以直接 push：
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' push"
+```
+
+**push 成功必须有证据**：
+- git push 输出包含 `To <remote>` 和实际推送范围（如 `<old-hash>..<new-hash>`）
+- exit code 为 0
+- 否则标记为 ❌ 推送失败 / 状态未知
+
+**记录 final pushed hash**：
+```powershell
+powershell.exe -Command "git -C '<项目路径>' rev-parse HEAD"
+```
+保存为 `<final-pushed-hash>`。
+
+**commit hash 双标注**：
+- 如果 `<pre-pull-hash>` ≠ `<final-pushed-hash>`，在执行日志中分别记录：
+  ```
+  - **pre-pull local commit hash**: <pre-pull-hash>
+  - **final pushed hash**: <final-pushed-hash>
+  ```
+- 后续 archive 阶段读取时以 `<final-pushed-hash>` 为准
+
+不用 `--no-verify`、`--no-gpg-sign` 等跳过 hook 的参数。
+
+## 步骤 7：收尾引导
+
+**worktree 模式（requested=true）**：不清理 worktree，**直接继续下方「worktree 合并流程」**。
+
+**主目录模式 Worktree 清理**：如果当前在 worktree 中，询问用户是否删除：
+- 是 → 先确认分支已推送 origin，再 `git worktree remove` + `git branch -D`
+- 否 → 保留
+
+> ⚠️ `git worktree remove` 在 Windows 下常因残留 `node_modules` 等深嵌套 gitignored 文件失败（"Directory not empty"）。完整兜底方法（robocopy /MIR 清空 + .NET 删空目录、ExitWorktree 限制、PreToolUse hook 对 `/MIR` 的误判规避）见 `reference.md`「Worktree 清理兜底（Windows）」。
+
+**产出归档引导**：展示 `.harness/changes/<change-name>/` 下的所有产出文件，询问用户：
+- 保留 → 后续可运行 harness-archive 归档
+- 归档 → 运行 harness-archive
+- 清理 → 删除 `.harness/changes/<change-name>/` 目录
+
+**append `phase.end` 事件**（submit 段；`note` 含结束时间、耗时、结果、final pushed hash、验证策略、摘要）：
+
+---
+
+## worktree 合并流程（步骤 M0–M8）
+
+> worktree 模式 commit 成功后自动执行；用户仅说「合并分支」/`/harness-merge` 且已有本地 commit 时从 M0 重入。合并方式固定 `--no-ff`；冲突 → 停下 → 用户手动解 → 确认后继续；**禁止 `checkout --theirs/--ours`**。
+
+### P0 合并稳定性门禁
+
+- 主分支名不硬编码，用 `git symbolic-ref --short refs/remotes/origin/HEAD` 读取
+- push 只在主分支；worktree 分支不 push
+- 所有 git 命令通过 `powershell.exe -Command "..."` 执行
+
+### 步骤 M0：启动合并段
+
+append `phase.start`（`--phase merge`；`note` 含 worktree 分支、主分支、ledger diffHash、验证策略；重入时 note 标注「重入 merge」）。
+
+### 步骤 M1：切回主目录主分支
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' symbolic-ref --short refs/remotes/origin/HEAD"
+powershell.exe -Command "git -C '<项目路径>' stash"   # 主目录有未提交变更时
+powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref HEAD"
+```
+
+不在主分支则 `git checkout <主分支>`。
+
+### 步骤 M2：fetch + 同步主分支
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' fetch origin"
+powershell.exe -Command "git -C '<项目路径>' pull --rebase"
+```
+
+pull 输出非 `Already up to date.` → 引入他人提交 → M4 必须重跑验证。
+
+### 步骤 M3：合并 worktree 分支
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' merge --no-ff worktree/<change-name>"
+```
+
+合并消息默认 `Merge branch 'worktree/<change-name>'`，用户可改文案，**方式固定 --no-ff**。
+
+### 步骤 M4：冲突处理
+
+若输出 `CONFLICT`：
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' diff --name-only --diff-filter=U"
+```
+
+- 列出冲突文件，**停下**，提示用户手动解决（编辑 → `git add` → `git commit`）
+- 状态 `🟡WARN(merge 冲突，待手动解决：<文件列表>)`
+- 用户确认解决后重跑 submit（从 M0 重入）
+- **禁止自动 `git checkout --theirs/--ours`**
+
+### 步骤 M5：合并后验证（ledger 复用优先）
+
+- 步骤 M2 引入他人提交 → **必须重跑** 构建+测试
+- 否则 diffHash 一致且 post-test 非行为性 → 🔁REUSED
+
+重跑后写回 ledger 的 `compile`/`unitTest`，更新 `diffHash`/`currentHead`。
+
+### 步骤 M6：push 主分支
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' fetch"
+powershell.exe -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+```
+
+远端有新提交 → 回 M2；无则：
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' push"
+```
+
+记录 `mergeFinalHash`：`git rev-parse HEAD`。
+
+### 步骤 M7：清理 worktree
+
+```powershell
+powershell.exe -Command "git -C '<项目路径>' worktree remove '<worktree-path>' --force"
+powershell.exe -Command "git -C '<项目路径>' branch -D worktree/<change-name>"
+```
+
+> Windows 兜底见 `reference.md`「Worktree 清理兜底（Windows）」。
+
+更新 `meta/worktree.json`：`created=false` + `removedAt`/`removedBy`/`removalNote`。
+
+### 步骤 M8：更新 ledger + 收尾
+
+ledger 顶层写入 `"mergeFinalHash": "<hash>"`；append `phase.end`（merge 段）。
+
+```markdown
+## 合并完成 — <change-name>
+
+- Merge commit: `<merge-commit-hash>`
+- 主分支 push: ✅（<old>..<new> → origin/<主分支>）
+- mergeFinalHash: `<merge-final-hash>`
+- 验证策略: 🔁REUSED / 🔄已重跑
+- worktree: 已清理
+- 下一步: `/harness-archive`
+```

package/resources/harness/bundles/java/claude-code/harness-submit/reference.md

@@ -0,0 +1,152 @@
+---
+description: harness-submit 的提交格式、固定交互模板和中文 commit 文件流程。仅在执行提交流程时读取。
+---
+
+# harness-submit 参考
+
+## 提交方式 AskUserQuestion 固定模板
+
+问题标题：`请选择提交方式`
+
+选项：
+
+1. `commit + push 到当前 upstream`
+2. `仅本地 commit，不 push`
+3. `取消提交`
+
+不得临场增加复杂对象或嵌套参数，避免 AskUserQuestion 参数错误。
+
+> **worktree 模式（meta/worktree.json requested=true）**：固定选项 2「仅本地 commit」，不展示「commit+push」；commit 成功后 skill **自动接续** worktree 合并流程（`/harness-merge` 为别名）。push 只在主分支完成，产出 `mergeFinalHash`。
+
+## Commit Message 固定格式
+
+```text
+<type>(<scope>): <中文摘要>
+
+- 变更点 1
+- 变更点 2
+
+验证：
+- <复用 ledger / 重跑验证摘要>
+```
+
+禁止 footer：
+
+```text
+Co-Authored-By: ...
+Generated by ...
+AI generated ...
+```
+
+## 中文 commit 文件流程
+
+1. 创建 runtime 目录：
+
+```powershell
+powershell.exe -NoProfile -Command "New-Item -ItemType Directory -Force '.harness/changes/<change>/runtime'"
+```
+
+2. 写入 message 文件：
+
+```text
+.harness/changes/<change>/runtime/commit-message.txt
+```
+
+3. 用户确认后提交：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' commit -F '.harness/changes/<change>/runtime/commit-message.txt'"
+```
+
+禁止：
+
+- 命令行内联长中文 commit message；
+- 先英文 commit，再 amend 成中文；
+- 使用 `--no-verify`、`--no-gpg-sign`。
+
+## Commit Message 确认模板
+
+```markdown
+## 准备提交
+
+### 1. Staged 文件
+<git diff --cached --name-only 的实际输出>
+
+### 2. Diff Stat
+<git diff --cached --stat 的实际输出>
+
+### 3. Commit Message
+```text
+<commit message 完整内容>
+```
+
+### 4. Push 策略
+commit + push / 仅本地 commit
+
+确认提交吗？
+1. 确认提交
+2. 修改 message
+3. 取消
+```
+
+## 远端检查
+
+push 前必须执行：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' fetch"
+powershell.exe -NoProfile -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+```
+
+远端有新提交时，必须让用户选择：
+
+1. rebase 后重跑必要验证；
+2. 停止 push，保留本地 commit。
+
+## 输出示例
+
+```markdown
+## 提交完成 — <change-name>
+
+- Commit: `<final-hash>`
+- Push: ✅ 已推送 / ⏭️ 仅本地 commit
+- Commit message: `.harness/changes/<change>/runtime/commit-message.txt`
+- 验证策略: 🔁 复用 test ledger / 🔄 已重跑
+- 下一步: `/harness-archive`
+```
+
+## Worktree 清理兜底（Windows）
+
+`git worktree remove <path>` 在 Windows 下常因目录残留 `node_modules` 等深嵌套 gitignored 文件失败（报 "Directory not empty"，git 无法删空目录）。按顺序兜底：
+
+1. **先删 git 注册和本地分支**（分支须已推送 origin）：
+   ```powershell
+   powershell.exe -Command "git -C '<项目路径>' worktree remove '<worktree-path>' --force"
+   powershell.exe -Command "git -C '<项目路径>' branch -D <branch>"
+   ```
+
+2. **若目录仍残留**（git 注册已移除但磁盘目录还在）：用 robocopy 空 source 镜像清空（能处理长路径与 `node_modules` 深嵌套）：
+   ```powershell
+   powershell.exe -Command "$empty=Join-Path $env:TEMP ('emp-'+[Guid]::NewGuid()); New-Item -ItemType Directory -Force $empty | Out-Null; robocopy $empty '<worktree-path>' /MIR | Out-Null; Remove-Item -Recurse -Force $empty"
+   ```
+   ⚠️ **hook 误判规避**：不要把 `robocopy ... /MIR` 和 `Remove-Item` 写在同一条命令的参数位——PreToolUse hook 会把 `/MIR` 误判为 `Remove-Item` 的受保护路径（报 "system path '/MIR' is blocked"）。若遇此误判，按工具失败恢复策略**拆成两条命令**分别执行，不要重复同一条失败命令。
+
+3. **目录清空后删空目录本身**（用 .NET，规避 Remove-Item 对系统路径的 hook 拦截）：
+   ```powershell
+   powershell.exe -Command "[System.IO.Directory]::Delete('<worktree-path>', $true)"
+   ```
+
+4. **ExitWorktree 工具限制**：`ExitWorktree(remove)` 只删由 `EnterWorktree` 创建的 worktree。若本会话进入的是已存在 worktree（由 `harness-run` 创建），工具会拒绝删除。此时用 `action:keep` 返回主仓库，再按上述 1-3 步手动清理。
+
+5. **清理后更新 `meta/worktree.json`**：置 `created=false` + 追加 `removedAt`/`removedBy`/`removalNote`，记录产出保留待 `/harness-archive`。
+
+> 含 `$`/`[Guid]`/`@{}` 的复杂命令建议写入 `scripts/*.ps1` 后 `-File` 执行，避免内联转义问题（参见 `../protocols/powershell-protocol.md`）。
+
+## 工作树 clean + 已有 wip commit 场景
+
+若进入 `/harness-submit` 时工作树已 clean（`git status --porcelain` 为空），且 run/test 阶段已做 wip commit（HEAD 已是本次变更的提交），则：
+
+- 步骤 1（合并最新代码）：按无 upstream / 远端无新提交判定 N/A，在执行日志记录理由。
+- 步骤 5（commit-message.txt + `git commit -F`）N/A：无可暂存 diff，无新 commit 需生成。执行日志标注 `commit-message.txt / git commit -F: N/A（工作树 clean，无新 commit；N 个 wip 提交已存在，原样推送）`。
+- 步骤 4（提交方式选择）：固定三选项仍适用。但当 review 标了 RED 兼容性破坏等需人工确认项时，可在"commit + push"选项的描述中注明"并确认 <RED 项>"，**不得新增第四选项**、不得临场拼复杂 AskUserQuestion 参数。
+- push 仍按步骤 6：fetch 检查远端 → `git push -u`（无 upstream 则新建远端分支）→ 记录 pre-pull hash + final pushed hash。

package/resources/harness/{general → bundles/java/claude-code}/harness-sync/SKILL.md

@@ -19,7 +19,7 @@ disallowed-tools:
   - Bash(awk *)
   - Bash(curl *)
 ---
-<!-- generated by harness_deploy.py; core=76dd32302df53f0b; overlay=none; do not edit -->
+<!-- generated by harness_deploy.py; core=c7f197c6a6f1ff5a; overlay=java; agent=claude-code; do not edit -->
 # harness-sync — 元数据同步
 
 ## Purpose
@@ -43,7 +43,7 @@ disallowed-tools:
 | 4 | CLAUDE.md 完整性/行数 → 超限 AskUserQuestion 瘦身 |
 | 5 | AGENTS.md 与 CLAUDE.md 一致 |
 | 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；可选 `harness_deploy.py diff` 检查已装 skill 是否过期 |
-| 7–9 | `.claude/rules/`、构建配置、测试目录 — **只提示不自动修复** |
+| 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
 
 状态判断表格、修复动作、输出示例 → `reference.md`