hunter-harness 0.2.0 → 0.2.1

package/resources/harness/bundles/java/codex/harness-package/checklist.md

@@ -1,322 +0,0 @@
----
-description: harness-package 的8步工作流详细步骤、模块识别方法和执行日志记录格式。仅在执行打包流程时读取。
----
-
-# harness-package 检查清单
-
-## 步骤 0：启动准备
-
-确定变更名：用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。默认最多一个未归档变更；如有多个，优先取最近修改的，或用 AskUserQuestion 询问用户。
-
-如果 `$ARGUMENTS` 非空且与检测到的变更名不一致，以 `$ARGUMENTS` 为准。
-
-**读取 worktree 状态并切换**：读 `.harness/changes/<change-name>/meta/worktree.json`（旧路径 `worktree.json` 兼容）。`requested=true` 且 `.claude/worktrees/<change-name>/` 已创建 → cd 到该 worktree 目录；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回主目录；`requested=false` → 在主目录执行。切换后检查构建配置文件（`.mvn/maven.config`、`settings-*.xml` 等）是否完整，缺失时从主目录复制。
-
-**强制前置检查 — harness-test（硬门禁）和 harness-review（参考性）**：
-
-通过 Glob 检查：
-- `.harness/changes/<change-name>/reports/test/test-report-*.md` 是否存在（旧路径 `tests/` 兼容）
-- `.harness/changes/<change-name>/reports/review/review-report-*.md` 是否存在（参考性，不阻塞；旧路径 `reviews/` 兼容）
-
-如果缺失 test 报告，使用 `AskUserQuestion` 询问用户：
-
-```
-检测到 harness-test 尚未运行（缺少测试报告）：
-- 测试报告: <存在/缺失>
-- 审查报告: <存在/缺失>（参考性，不阻塞）
-
-打包前建议先运行测试。请选择：
-1. 先运行 harness-test — 退出 package 流程，运行 harness-test 后再 package（推荐）
-2. 跳过测试继续打包 — 风险自担，报告中明确标记
-3. 取消 package
-```
-
-**默认不跳过 test**。用户确认跳过时，必须在执行日志和 package-report 中明确写明：
-- 执行日志：`- **跳过**: 用户确认跳过 harness-test`
-- package-report：`> ⚠️ 用户确认跳过 harness-test，打包结果未经测试验证`
-
-**review 报告**：如果存在，记录路径和摘要供参考；如果不存在，不阻塞 package。review 结果不作为硬门禁。
-
-**读取 verification-ledger + 确定 baseCommit**：
-
-1. 读取 `.harness/changes/<change-name>/evidence/verification-ledger.json`（旧路径 `verification-ledger.json` 兼容），记录 `unitTest`/`apiTest` 的 status、`diffHash`、`currentHead`
-2. 确定 `baseCommit`：优先取 `.harness/changes/<change-name>/logs/execution-log.md` 中 harness-submit 阶段的 `final pushed hash`（旧路径 `execution-log.md` 兼容）；无 submit 记录时取当前 `git rev-parse HEAD`
-3. 判断 ledger 是否有效（全部满足才算有效）：
-   - `unitTest.status=OK` 且 `apiTest.status=OK`
-   - `diffHash` 与当前提交一致
-   - submit 后无新提交（`git log <baseCommit>..HEAD` 为空）
-   - 无行为性 post-test 修改（`postTestClassification` ∈ {无, NON_BEHAVIORAL_CLEANUP, COMMENT_ONLY, TEST_ONLY}）
-4. ledger 有效 → 默认 `mvn package -DskipTests` 复用测试；ledger 无效 → 带测试打包或要求先跑 `/harness-test`
-
-**append `phase.start`**（含 worktree/baseCommit/ledger 摘要于 `note`）：
-
-```powershell
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase package --type phase.start --note "<触发指令>"
-```
-
-## 步骤 1：拉取最新代码
-
-> **分支名自动读取**：不硬编码 `master` 或 `main`，使用 `git rev-parse --abbrev-ref @{u}` 自动读取 upstream 分支。
-
-合并他人提交，确保打包基于最新代码：
-
-```powershell
-# 0. 自动读取当前分支的 upstream
-powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref @{u}"
-# 输出示例：origin/master 或 origin/develop
-
-# 1. 暂存当前变更
-powershell.exe -Command "git -C '<项目路径>' stash"
-
-# 2. 拉取远程最新代码（使用读取到的 upstream）
-powershell.exe -Command "git -C '<项目路径>' pull"
-
-# 3. 恢复暂存的变更
-powershell.exe -Command "git -C '<项目路径>' stash pop"
-```
-
-**冲突处理**：
-- `git stash pop` 产生冲突 → **停止打包流程**，提示用户手动解决冲突
-- `git pull` 失败（网络问题）→ 提示用户检查网络，询问是否继续（基于本地代码打包）
-- 无冲突 → 继续步骤 2
-
-**Shell 安全规则（强制）**：
-- 如果 `git stash` / `git pull` 命令被 hook 拒绝（输出含 `Denied` / `PreToolUse:Bash hook error`），**必须停止流程**或重试 PowerShell 调用
-- **不得基于被拒绝的输出继续后续步骤**（不能假装"拉取成功"）
-- 拉取成功的判断证据：git 输出包含 `Already up to date.` 或 `Fast-forward`、`Updating <hash>..<hash>`，且 exit code 为 0
-
-## 步骤 2：合并后重新验证（ledger 复用优先）
-
-合并后必须重新编译；测试是否重跑按 ledger 有效性决定。
-
-**ledger 有效时**（步骤 0 已判定）：跳过 `mvn test`，仅执行 `mvn compile` 确认合并后可编译，测试结果复用 ledger。
-
-**ledger 无效时**：执行 `mvn compile` + `mvn test`，结果写回 ledger。
-
-**合并后重新验证前，先检查依赖模块**：
-```powershell
-# 检查上游依赖模块是否已 install 到本地仓库
-powershell.exe -Command "Test-Path '$env:USERPROFILE\.m2\repository\<group-path>\<module>\*\*.jar'"
-```
-如果缺失，先安装：
-```powershell
-powershell.exe -Command "mvn install -pl <upstream-modules> -am -DskipTests -nsu"
-```
-
-```powershell
-# 编译验证（始终执行）
-powershell.exe -Command "mvn compile -pl <module> -am"
-
-# 测试验证（仅 ledger 无效或用户要求 package-with-tests 时执行）
-powershell.exe -Command "mvn test -pl <module> -am"
-```
-
-**编译/测试成功必须有明确证据**：
-- `mvn compile` 输出必须包含 `BUILD SUCCESS`
-- `mvn test` 输出必须包含 `Tests run: N, Failures: 0, Errors: 0`
-- 命令被 hook 拒绝或 exit code 非 0 → 标记为 ❌ 失败，停止流程
-
-**pull 后远程变更检查**：
-```powershell
-# 检查 pull 是否引入了他人提交
-powershell.exe -Command "git -C '<项目路径>' log HEAD@{1}..HEAD --oneline"
-```
-- 如果有他人提交（输出非空），**ledger 失效**，必须重新 compile + test，即使 pull 前已验证过
-- 如果没有他人提交（输出为空），ledger 仍然有效，可基于已有验证结果继续
-
-**验证失败处理**：
-- 编译失败 → 分析是否与本次变更相关。相关则修复后重试；无关（他人引入的问题）则记录并询问用户是否继续
-- 测试失败 → 分析失败原因。如果是他人代码破坏了本次功能，记录冲突点并提示用户
-
-> **为什么合并后必须重新编译**：他人代码可能引入新依赖（编译失败）、修改公共接口（调用点断裂）、修改数据库结构（测试数据不匹配）。即使 git 自动合并无冲突，语义层面可能存在冲突。ledger 复用仅在 pull 未引入他人提交时成立。
-
-## 步骤 3：变更模块识别
-
-**变更模块识别必须区分四种来源，不得把远程他人变更误判为本次变更**：
-
-| 来源 | git 命令 | 用途 |
-|------|---------|------|
-| a. 本地未提交变更（工作区） | `git diff --name-only` | 当前正在编辑但未 add 的变更 |
-| b. staged 变更 | `git diff --cached --name-only` | 已 add 但未 commit 的变更 |
-| c. 已提交但未推送变更 | `git log @{u}..HEAD --name-only --pretty=format:` | 本次开发的本地提交 |
-| d. 远程 pull 进来的他人变更 | `git log HEAD@{1}..HEAD --name-only --pretty=format:` | pull 引入的他人提交，**不得纳入本次变更模块** |
-
-**识别本次变更模块的标准来源**：
-- 本次开发涉及的变更 = a + b + c（工作区 + staged + 本地未推送提交）
-- 远程 pull 进来的 d 是他人变更，仅作为"合并验证"对象，不写入本次打包变更模块清单
-
-1. **确定本次变更比较基线**：使用 upstream（不硬编码 master/main）：
-
-```powershell
-# 自动读取 upstream 名称
-powershell.exe -Command "git -C '<项目路径>' rev-parse --abbrev-ref @{u}"
-# 输出示例：origin/master
-
-# 计算 merge-base
-powershell.exe -Command "git -C '<项目路径>' merge-base HEAD '@{u}'"
-```
-
-2. **获取本次变更文件列表（排除 pull 进来的他人变更）**：
-
-```powershell
-# 获取本地未提交+本地已提交（不含远程拉入的他人提交）
-powershell.exe -Command "git -C '<项目路径>' diff '@{u}'...HEAD --name-only"
-```
-
-> 注意 `...HEAD`（三点）会自动排除从 upstream 合并进来的他人提交，只保留本地分叉后的变更。
-
-3. **映射到 Maven 模块**：逐个检查变更文件的路径，判断其所属的 Maven 模块：
-   - 找到变更文件所在目录及其父目录中的 `pom.xml`
-   - 模块路径 = `pom.xml` 所在目录的相对路径（如 `module-a/sub-module-b`）
-   - 同一模块的多个变更文件只记录一次
-   - 根目录 `pom.xml` 的变更属于父项目本身（用根路径 `.` 表示）
-
-4. **识别依赖链**：对每个变更模块，检查哪些其他模块依赖它：
-   - 扫描其他模块的 `pom.xml` 中 `<dependency>` 引用了变更模块的 `<groupId>:<artifactId>`
-   - 这些下游模块也需要打包（对应 Maven `-amd` 参数）
-   - 上游依赖模块（变更模块自身依赖的模块）由 `-am` 自动包含
-
-5. **输出模块清单**：汇总所有变更模块 + 依赖链涉及模块，展示给用户：
-
-```markdown
-## 变更模块识别结果
-
-### 直接变更模块 (N 个)
-- `module-a` — 变更文件: 5 (src/main/java/..., src/main/resources/...)
-- `module-b/sub-b` — 变更文件: 2
-
-### 依赖链涉及模块
-- 上游（-am）: parent-pom, module-common
-- 下游（-amd）: module-web (依赖 module-a)
-
-### 未变更模块（将跳过）
-- module-c, module-d
-```
-
-## 步骤 4：打包模式选择
-
-使用 AskUserQuestion 向用户展示选项：
-
-```markdown
-已识别 N 个变更模块及其依赖链，请选择打包模式：
-
-1. 增量打包 — 只打包变更模块 + 上游依赖（-pl <modules> -am）
-   适用：日常发版，构建速度快
-   命令：mvn package -pl module-a,module-b/sub-b -am
-
-2. 增量打包（含下游） — 打包变更模块 + 上游 + 下游（-pl <modules> -am -amd）
-   适用：需要验证下游模块兼容性
-
-3. 全量打包 — 打包所有模块
-   适用：首次发版、重大重构、不确定依赖关系时
-   命令：mvn package
-
-4. 自定义 — 手动指定模块列表
-```
-
-降级策略：用户无明确偏好时，默认选择选项 1（增量打包 + 上游依赖）。
-
-## 步骤 5：执行打包
-
-根据步骤 4 的选择构建 Maven 命令。**是否带 `-DskipTests` 由 ledger 有效性决定**：
-
-**ledger 有效时（默认）**：复用 test 阶段验证，跳过测试
-
-```powershell
-# 增量打包（选项 1）
-powershell.exe -Command "mvn package -pl <module-list> -am -DskipTests"
-# 增量打包含下游（选项 2）
-powershell.exe -Command "mvn package -pl <module-list> -am -amd -DskipTests"
-# 全量打包（选项 3）
-powershell.exe -Command "mvn package -DskipTests"
-```
-
-**ledger 无效时或用户要求 package-with-tests**：去掉 `-DskipTests`
-
-```powershell
-powershell.exe -Command "mvn package -pl <module-list> -am"
-```
-
-**关键规则**：
-- **ledger 有效时默认 `-DskipTests`**，复用 test 阶段的 unitTest + apiTest 结果（不是"跳过测试"，是"复用已验证结果"）
-- ledger 无效 / 用户要求 `package-with-tests` / test 报告缺失 → 必须带测试打包
-- `-pl` 中的模块路径使用相对于根 pom.xml 的路径，多模块用逗号分隔
-- 记录开始时间用于计算耗时
-- 打包失败时**立即停止**，不继续后续步骤，转入错误处理
-
-**失败处理**：
-- 输出失败模块名称和错误信息
-- 提示用户检查：
-  1. 依赖是否完整（是否需要先 `mvn install` 安装上游模块）
-  2. 版本冲突（参考 `reference.md` 常见问题）
-  3. 编译错误（是否遗漏了某个变更文件）
-- 用 AskUserQuestion 询问用户：重试 / 调整模块范围 / 停止
-
-## 步骤 6：结果收集
-
-打包成功后，逐模块扫描产物（**必须通过 Glob 实际扫描确认，不能仅根据 Maven 输出猜测**）：
-
-1. **扫描 target/ 目录**：对每个打包模块，用 **Glob 工具实际扫描**：
-
-```
-<module-path>/target/*.jar
-<module-path>/target/*.war
-```
-
-2. **收集信息**（基于 Glob 实际返回的文件）：
-   - 产物文件名
-   - 产物相对路径（相对于项目根目录）
-   - 文件大小（用 `powershell.exe -Command "Get-Item '<path>' | Select-Object Length"` 获取）
-   - **sha256**（必填，用于 ledger 和部署校验：`powershell.exe -Command "Get-FileHash '<path>' -Algorithm SHA256"`）
-
-3. **构建状态判定（必须基于实际证据）**：
-   - ✅ SUCCESS — Glob 扫描确认 target/ 中存在预期的 jar/war 文件 + Maven 输出含 `BUILD SUCCESS`
-   - 🟡 SKIPPED — 模块不含主产物（如 parent-pom 模块只有 pom.xml）
-   - ❌ FAILED — 打包命令报错（已在步骤 5 处理）/ Glob 扫描未找到产物 / Maven 输出含 `BUILD FAILURE`
-
-4. **汇总产物表**：
-
-```markdown
-| 模块 | 产物 | 路径 | 大小 | 状态 |
-|------|------|------|------|------|
-| module-a | xxx-service.jar | module-a/target/xxx-service-1.0.jar | 12.5 MB | ✅ SUCCESS |
-| module-web | xxx-web.war | module-web/target/xxx-web-1.0.war | 45.2 MB | ✅ SUCCESS |
-| parent-pom | — | — | — | 🟡 SKIPPED |
-```
-
-## 步骤 7：持久化报告 + 写回 ledger
-
-将打包报告写入 `.harness/changes/<change-name>/reports/package/package-report-YYYYMMDD-HHmm.md`。
-
-时间戳取当前时间，格式 `YYYYMMDD-HHmm`（如 `20260617-1430`）。
-
-报告内容格式见 `reference.md` 的"报告格式示例"。报告必须包含「测试执行策略」段落（见 reference.md）。
-
-**写回 `evidence/verification-ledger.json` 的 `package` 项**：
-
-```json
-"package": {
-  "status": "OK",
-  "command": "mvn package -pl <module> -am -DskipTests",
-  "baseCommit": "<final pushed hash 或当前 HEAD>",
-  "deployArtifact": "<module>/target/<artifact>.jar",
-  "sha256": "<artifact sha256>",
-  "testsExecuted": false,
-  "testsReusedFrom": "unitTest+apiTest",
-  "evidence": "BUILD SUCCESS + Glob 扫描确认 jar 存在",
-  "startedAt": "...",
-  "finishedAt": "...",
-  "durationMs": 0
-}
-```
-
-- `testsExecuted`：本次 package 是否真实跑了测试（ledger 有效且用了 `-DskipTests` → false）
-- `testsReusedFrom`：`testsExecuted=false` 时必须指明复用来源（`unitTest+apiTest`）
-
-## 步骤 8：events 结束
-
-**append `phase.complete`**（`note` 含 baseCommit/打包策略/结果/报告路径）：
-
-```powershell
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase package --type phase.complete --note "OK|WARN|FAIL — <摘要>"
-```

package/resources/harness/bundles/java/codex/harness-package/reference.md

@@ -1,210 +0,0 @@
----
-description: harness-package 的Maven打包参数速查、增量vs全量对比、常见问题处理和报告格式示例。仅在需要参考参数细节或处理问题时读取。
----
-
-# harness-package 参考 — 参数、问题与格式
-
-## Maven 打包参数速查
-
-| 参数 | 说明 | 示例 |
-|------|------|------|
-| `-pl <modules>` | 指定构建模块列表（逗号分隔） | `-pl module-a,module-b/sub-b` |
-| `-am` | 同时构建指定模块的上游依赖（Also Make） | `-pl module-a -am` |
-| `-amd` | 同时构建依赖指定模块的下游模块（Also Make Dependents） | `-pl module-a -amd` |
-| `-DskipTests` | 跳过测试执行（**ledger 有效时默认使用**，复用 test 阶段验证） | `mvn package -DskipTests` |
-| `-Dmaven.test.skip=true` | 跳过测试编译和执行（更激进，连测试代码都不编译） | 不推荐使用 |
-| `-T 4` | 并行构建，4个线程 | `mvn package -T 4` |
-| `-o` | 离线模式（不从远程仓库下载） | `mvn package -o` |
-| `-DfinalName=<name>` | 指定最终产物名称 | `-DfinalName=my-app` |
-| `--batch-mode` | 非交互模式（CI 场景） | `mvn package --batch-mode` |
-
-## 可选配置（package 时序与测试策略）
-
-在 `.harness/config/harness-test-config.md` 中可配置 package 行为：
-
-```yaml
-package:
-  preferred-order: after-submit   # 默认：package 在 submit 之后运行
-  allow-before-submit: true       # 允许发版前打包（submit 之前）；false 时 package 启动检查 submit 是否已运行
-  reuse-ledger-tests: true        # 默认：ledger 有效时用 -DskipTests 复用 test 阶段验证
-  force-with-tests: false         # 强制带测试打包（等同 package-with-tests）
-```
-
-- `preferred-order: after-submit`：package 的 `baseCommit` 取 submit 日志的 final pushed hash
-- `allow-before-submit: true`：允许在 submit 之前运行 package，此时 `baseCommit` 为当前 HEAD；submit 后若 pull 引入新提交，须重新 package
-- `reuse-ledger-tests: true`：ledger 有效时默认 `-DskipTests`，报告标明复用来源；ledger 无效时自动改为带测试打包
-
-> 未配置时使用上述默认值。
-
-## 增量 vs 全量对比
-
-| 维度 | 增量打包 | 全量打包 |
-|------|----------|----------|
-| **命令** | `mvn package -pl <modules> -am` | `mvn package` |
-| **适用场景** | 日常发版、局部变更、迭代开发 | 首次发版、重大重构、不确定依赖关系 |
-| **构建范围** | 变更模块 + 上游依赖 | 所有模块 |
-| **构建速度** | 快（只构建相关模块） | 慢（全量构建） |
-| **风险** | 可能遗漏间接依赖 | 无遗漏风险 |
-| **产物数量** | 只产出相关模块的 jar/war | 产出所有模块的 jar/war |
-| **推荐优先级** | 首选（默认模式） | 增量失败时的降级方案 |
-
-**何时选择全量**：
-- 首次部署或项目初始化
-- pom.xml 结构发生重大变更
-- 依赖关系不确定或增量打包出现版本冲突
-- 用户明确要求全量构建
-
-## 常见问题处理
-
-| 问题 | 原因 | 处理方法 |
-|------|------|----------|
-| **合并冲突** | 他人代码与本次变更有重叠 | 停止打包流程，提示用户手动解决冲突后重新运行 |
-| **合并后编译失败** | 他人代码引入新依赖或修改公共接口 | 分析错误是否与本次变更相关，相关则修复，无关则记录并询问用户 |
-| **合并后测试失败** | 他人代码破坏了本次功能 | 记录冲突点，提示用户协调解决 |
-| **打包失败：找不到依赖** | 上游模块未安装到本地仓库 | 先执行 `mvn install -pl <upstream> -am`，再打包 |
-| **打包失败：版本冲突** | 同一依赖多个版本，SNAPSHOT 冲突 | 检查 pom.xml 版本号，统一版本；或用 `-DallowConflictingSnapshots=true` |
-| **打包失败：编译错误** | 变更文件有语法错误或类型不匹配 | 先执行 `mvn compile` 定位错误，修复后重新打包 |
-| **打包失败：测试失败** | 单元测试或集成测试报错 | 检查测试日志，修复测试或用户确认后加 `-DskipTests` |
-| **打包失败：离线依赖缺失** | `-o` 模式下本地仓库缺少依赖 | 去掉 `-o`，加 `-nsu` 联网下载（见 `项目 maven-offline 规则`） |
-| **target/ 目录不存在** | 模块未被打包命令包含 | 检查 `-pl` 参数是否遗漏该模块，或改用全量打包 |
-| **增量打包遗漏产物** | `-am` 未包含足够的上游模块 | 检查依赖链，补充遗漏模块到 `-pl` 列表，或改用全量打包 |
-| **parent-pom 模块无 jar 产物** | 父 pom 模块只做依赖管理，不生成 jar | 正常行为，状态标记为 SKIPPED |
-| **war 包过大** | 包含了不必要的依赖或资源 | 检查 pom.xml 的依赖范围（scope），排除 provided/test 依赖 |
-| **并行构建报错** | 模块间存在循环依赖或线程竞争 | 去掉 `-T` 参数，改用串行构建 |
-
-**依赖缺失的典型解决流程**：
-
-```powershell
-# 1. 先安装所有上游依赖到本地仓库
-powershell.exe -Command "mvn install -pl module-common,module-parent -am"
-
-# 2. 再对变更模块执行增量打包
-powershell.exe -Command "mvn package -pl module-a -am"
-```
-
-## 报告格式示例
-
-```markdown
----
-change-name: user-auth-feature
-package-mode: incremental
-generated-at: 2026-06-17 14:30:00
-base-commit: abc1234
-base-commit-source: submit final pushed hash
-maven-command: mvn package -pl module-auth,module-api -am -DskipTests
-tests-executed: false
-tests-reused-from: unitTest+apiTest
-ledger-diff-hash: sha256:...
----
-
-# 打包报告 — user-auth-feature
-
-## 打包概要
-
-| 项目 | 值 |
-|------|-----|
-| 变更名 | user-auth-feature |
-| 打包模式 | 增量（-pl + -am） |
-| Maven 命令 | `mvn package -pl module-auth,module-api -am -DskipTests` |
-| 基准 commit | abc1234（来源：submit final pushed hash） |
-| 开始时间 | 2026-06-17 14:25:00 |
-| 结束时间 | 2026-06-17 14:30:00 |
-| 构建耗时 | 5分0秒 |
-| 构建结果 | SUCCESS |
-
-## 测试执行策略
-
-- package 本次是否执行 tests: **否**（`-DskipTests`）
-- 复用来源: verification-ledger 的 `unitTest` + `apiTest`（status=OK）
-- ledger diffHash: sha256:...
-- 复用成立条件: diffHash 一致 + submit 后无新提交 + 无行为性 post-test 修改
-- 若 ledger 无效: 改为"是（带测试打包）"并说明原因（test 未跑 / diffHash 不一致 / submit 后有新提交 / 行为性 post-test 修改）
-
-## 变更模块
-
-### 直接变更模块 (2 个)
-
-| 模块 | 变更文件数 | 变更类型 |
-|------|-----------|----------|
-| module-auth | 5 | 新增+修改 |
-| module-api | 2 | 修改 |
-
-### 依赖链模块
-
-| 类型 | 模块 |
-|------|------|
-| 上游依赖 (-am) | parent-pom, module-common |
-| 下游依赖 (-amd) | 未包含 |
-
-## 产物清单
-
-| 模块 | 产物文件名 | 相对路径 | 大小 | 状态 |
-|------|-----------|----------|------|------|
-| module-auth | auth-service-1.0.0.jar | module-auth/target/auth-service-1.0.0.jar | 12.5 MB | SUCCESS |
-| module-api | api-model-1.0.0.jar | module-api/target/api-model-1.0.0.jar | 3.2 MB | SUCCESS |
-| module-common | common-utils-1.0.0.jar | module-common/target/common-utils-1.0.0.jar | 8.1 MB | SUCCESS |
-| parent-pom | — | — | — | SKIPPED |
-
-**产物总计**: 3 个 jar, 总大小 23.8 MB
-
-## 构建日志摘要
-
-```
-[INFO] Reactor Build Order:
-  parent-pom  .................................. SKIPPED
-  module-common  ................................ SUCCESS [8.1s]
-  module-api  ................................... SUCCESS [3.2s]
-  module-auth  .................................. SUCCESS [12.5s]
-[INFO] BUILD SUCCESS
-```
-
-## 部署建议
-
-- 部署顺序：common-utils → api-model → auth-service（按依赖顺序）
-- 注意：auth-service 依赖 common-utils 和 api-model，确保目标环境已有这两个依赖
-```
-
-## 变更模块识别方法
-
-### 方法 1：git diff + pom.xml 映射（推荐）
-
-```powershell
-# 1. 获取基准 commit
-powershell.exe -Command "git -C '<项目路径>' merge-base HEAD origin/master"
-
-# 2. 获取变更文件列表
-powershell.exe -Command "git -C '<项目路径>' diff <base-commit> --name-only"
-
-# 3. 对每个变更文件，向上查找 pom.xml 所在目录
-#    变更文件: module-a/src/main/java/com/example/Service.java
-#    → pom.xml 在: module-a/pom.xml
-#    → 模块路径: module-a
-```
-
-### 方法 2：git diff + Maven Reactor 映射
-
-```powershell
-# 1. 获取变更文件列表
-powershell.exe -Command "git -C '<项目路径>' diff <base-commit> --name-only"
-
-# 2. 对变更目录执行 Maven 列出模块
-powershell.exe -Command "mvn -f <项目路径>/pom.xml help:active-profiles -pl :<module-artifactId>"
-```
-
-### 依赖链识别
-
-**上游依赖（-am）**：变更模块 pom.xml 中 `<dependencies>` 引用的同项目模块，由 Maven `-am` 参数自动处理。
-
-**下游依赖（-amd）**：需要扫描其他模块的 pom.xml，找出 `<dependency>` 中引用了变更模块 `<groupId>:<artifactId>` 的模块：
-
-```powershell
-# 扫描所有子模块 pom.xml 中对变更模块的引用（使用 Grep 工具更高效）
-Grep("<artifactId>module-a</artifactId>", "<项目路径>/", glob="**/pom.xml")
-```
-
-### 边界情况
-
-- **根 pom.xml 变更**：属于父项目，需全量打包
-- **多模块同一变更**：合并到 `-pl` 列表，用逗号分隔
-- **无变更文件**：提示用户确认是否需要全量打包
-- **新增模块**：pom.xml 本身是新增文件，需全量打包确保 Reactor 顺序正确

package/resources/harness/bundles/java/codex/harness-plan/SKILL.md

@@ -1,109 +0,0 @@
----
-name: harness-plan
-description: 将需求转化为设计文档+实施计划+完整测试场景表，必须在编码前完成。使用场景：需求分析、feature plan、技术方案设计、实现方案规划
----
-<!-- generated by harness_deploy.py; core=9a7af3c66acaad35; overlay=java; agent=codex; do not edit -->
-# harness-plan — 需求规划
-
-## Purpose
-
-需求 → 设计文档 → 任务拆分 → 测试场景表（编码/测试唯一真相源）。存在 `.harness/archive/` 或 `.harness/knowledge/` 时须先 `harness-knowledge-query`。
-
-## When to Use
-
-`/harness-plan`、新功能设计、技术方案、测试场景表规划。
-
-## 统一读取协议
-
-1. **`.harness/changes/<change-name>/` 是唯一真相源** — 所有输入从该目录读取，产物写入对应子目录
-2. **change-name 优先从 frontmatter 读取** — `spec/*-design.md`、`plans/*-plan.md` 的 YAML `change-name`
-3. **frontmatter 缺失时兼容旧格式** — 从路径推断，标记 `🟡 legacy-plan`，不失败
-4. **spec** — 设计真相源：`spec/<change>-design.md`
-5. **plan** — 任务真相源：`plans/<change>-plan.md`
-6. **implementation-detail** — 自适应执行参考；legacy 缺失 🟡WARN，不阻断
-7. **test-scenarios** — 测试真相源：`plans/<change>-test-scenarios.md`
-8. **禁止读取 `docs/superpowers/` 作为正式输入** — 旧草稿仅人工线索
-
-状态目录分层：新路径优先，旧路径兼容 → [[../protocols/state-layout-protocol.md|state-layout-protocol]]
-
-## Worktree 门禁
-
-读取 `meta/worktree.json`（兼容旧路径 `worktree.json`）：
-
-| 条件 | 行为 |
-|------|------|
-| `requested=false` | 主目录执行 |
-| `requested=true` + path 存在 | 切换 worktree 执行 |
-| `requested=true` + path 不存在 | **必须创建**（run）或 **停止**（test/review/submit） |
-
-**严禁** `requested=true` 时静默回主目录。创建失败 → 停止或 AskUserQuestion 降级（须 🟡WARN + 用户确认）。
-
-**状态与代码分离**：代码/编译/测试在 `worktreeRoot`；`stateDir`（logs/events/ledger/reports）写回 `.harness/changes/<change-name>/`。
-
-创建命令与 JSON 模板 → 各 skill `reference.md`（plan 写决策，run 创建/更新）。
-
-## 原生规划协议
-
-内化为 `protocols.md`：`clarification-protocol`、`decision-grilling-protocol`、`implementation-planning-protocol`。不运行时调用 Superpowers/grill-me。
-
-## Subagent 委派
-
-- **阶段 3 探索**：`check-agents --agent harness-explorer` → 可用则委派，否则主会话探索；无效返回不 retry
-- **阶段 7.5**：仅 `--adversarial`；`check-agents --agent harness-evaluator` → `reports/plan-review/`
-
-## Workflow 概要
-
-| 阶段 | 动作 |
-|------|------|
-| 0 | git status；脏工作区 → baseline 隔离 + `decision`，不询问 |
-| 0.5 | `harness-knowledge-query`（失败记 `issue`） |
-| 1 | 自动生成 change-name + 初始化 logs/events |
-| 2–3 | 代码探索 + 需求澄清（高风险 → 交互白名单 ②） |
-| 4 | **设计审批包** AskUserQuestion → 写 `spec/*-design.md` + `meta/worktree.json` |
-| 5–6 | plan + implementation-detail + test-scenarios → `plans/` |
-| 7.5 | 仅 `--adversarial` 对抗评审 |
-| 8 | 产物完整性必检 → `checklist.md` |
-
-change-name 范围变更 → 提示重命名或记 🟡WARN（→ `reference.md`）
-
-## P0 执行可信度规则
-
-- 命令结果不得靠猜测；普通 Bash 被拒 → 立即改用等价 PowerShell 重试一次
-- 仅 PowerShell 成功且有明确证据（构建/git/测试输出、文件存在、exit 0）时可标 ✅OK；否则 ❌FAIL 或 🟡WARN
-- 禁止把 hook 拒绝、静态验证、无输出、用户跳过说成成功 → 详见 [[../protocols/powershell-protocol.md|powershell-protocol]]、[[../protocols/evidence-based-reporting-protocol.md|evidence-based-reporting-protocol]]
-
-## 关键规则
-
-| 规则 | 要点 |
-|------|------|
-| 产物路径 | 只写 `.harness/changes/<cn>/`；禁止 superpowers 输入 |
-| 设计审批包 | 一次 AskUserQuestion 含 worktree（读 `harness.json` `defaultWorktree`） |
-| 阶段 8 | spec/plan/detail/scenarios/worktree.json/logs/events 缺一不可 → ❌FAIL |
-| Plan 结束 | **禁止**询问执行模式；只提示 `/harness-run` |
-| 知识查询 | 0.5 失败不得假装已读历史 |
-| 协议 | sensitive-info / evidence-based-reporting / state-layout |
-
-产出物表、frontmatter、legacy 兼容、结束输出模板 → `reference.md`
-
-## 渐进披露
-
-- **Read `checklist.md`** — 阶段检查与覆盖表
-- **Read `protocols.md`** — 阶段 4/6 原生协议
-- **Read `reference.md`** — 模板与 worktree JSON
-
-## 交互白名单
-
-1. **设计审批包**（阶段 4）：设计 + 场景表 + worktree + change-name
-2. **decision-grilling**（阶段 3 澄清）：高风险业务裁决（一次一问）
-
-## 执行日志
-
-`events.ndjson` 为唯一事实源（schema_version 2，`note` 承载人类可读摘要）；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。结构 → [[../protocols/report-pipeline-protocol.md|report-pipeline-protocol]]
-
-```powershell
-python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase <phase> --type phase.start --note "<触发指令>"
-```
-
-> **脚本接线**：`harness_events.py append`；`harness_archive.py finalize`；`harness_preflight.py check`；`harness_ledger.py can-reuse`；`harness_service.py ensure/stop`（须 `--files`/`serviceStart.inputFiles`）。JSON 输出按 D13 护栏解读。
-
-> **Task 4 §6.1 写入契约**：普通 `append` = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex` 无需去重扫描）。仅 `--type phase.end` append 在追加成功后渲染一次 `execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。高频 command append 期间 log 可能滞后，phase 边界保持最新。