hunter-harness 0.2.0 → 0.2.1

package/resources/harness/bundles/java/codebuddy/harness-submit/reference.md

@@ -1,152 +0,0 @@
----
-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/bundles/java/codebuddy/harness-sync/SKILL.md

@@ -1,65 +0,0 @@
----
-name: harness-sync
-description: 检查并更新项目AI元数据（CodeGraph索引、harness-codebase-map分析、CLAUDE.md、AGENTS.md、.harness/完整性），确保Claude对代码库的理解与最新代码一致。当用户说'同步/更新索引/刷新元数据/检查一致性'时使用
----
-<!-- generated by harness_deploy.py; core=c7f197c6a6f1ff5a; overlay=java; agent=codebuddy; do not edit -->
-# harness-sync — 元数据同步
-
-## Purpose
-
-检查并更新 AI 元数据（CodeGraph、codebase map、knowledge 索引、CLAUDE.md、AGENTS.md、`.harness/`），使理解与代码一致。
-
-## When to Use
-
-「同步/更新索引/刷新元数据」、提交前校准、archive/knowledge 变化后。跳过：刚 sync 且无新提交。
-
-## Workflow（薄编排）
-
-| Phase | 检查 → 动作 |
-|-------|-------------|
-| 0 | 读 SKILL + `reference.md` + protocols |
-| 1 | git log/diff 感知变更量 |
-| 2 | CodeGraph 索引是否需重建 |
-| 3 | `.harness/codebase/map/` 是否过期 → 报告建议 `/harness-codebase-map` |
-| 3.5 | `harness_knowledge.py sync`；可 `sync --update`；失败不得假装可用 |
-| 3.6 | 扫描 `.harness/knowledge/maintenance-outbox/{pending,failed}`；对每项运行 `harness_knowledge.py maintain --project . --archive-id <id> --json`（§8.2：archive close 只 enqueue，sync 异步推进 outbox 到 completed/completed_rules_pending_judge） |
-| 4 | CLAUDE.md 完整性/行数 → 超限 AskUserQuestion 瘦身 |
-| 5 | AGENTS.md 与 CLAUDE.md 一致 |
-| 6 | `.harness/` 结构（init 规程 → `reference.md` 第 6 步）；可选 `harness_deploy.py diff` 检查已装 skill 是否过期 |
-| 7–9 | `项目规则（见 .harness/context-index.json）/`、构建配置、测试目录 — **只提示不自动修复** |
-
-状态判断表格、修复动作、输出示例 → `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]]
-
-## 关键规则
-
-变更量先行 · CodeGraph 依赖编译产物 · map 与 Repomix 互斥 · CLAUDE 瘦身须用户确认 · Phase 7–9 只提示 · knowledge sync 失败记 WARN/FAIL
-
-## Output Format
-
-各组件状态表格 + 操作摘要 → `reference.md`
-
-## 渐进披露
-
-- **Read `reference.md`** — 10 步详细判定与修复
-
-## 交互白名单
-
-**仅** CLAUDE.md/AGENTS.md 瘦身拆分确认
-
-## 执行日志
-
-`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 边界保持最新。

package/resources/harness/bundles/java/codebuddy/harness-sync/reference.md

@@ -1,153 +0,0 @@
----
-description: harness-sync 的10步检查流程详细状态标准和修复动作。仅在执行完整元数据同步时读取。
----
-
-# harness-sync 参考 — 检查流程详情
-
-## 检查流程
-
-### 1. 感知代码变更
-
-用 PowerShell 执行 git 命令（项目路径含中文时必须通过 PowerShell）：
-
-```powershell
-powershell.exe -Command "git -C '<项目路径>' log --oneline -10"
-powershell.exe -Command "git -C '<项目路径>' diff --stat HEAD~5 2>$null"
-```
-
-了解最近变更范围（文件数、模块数），作为判断各组件是否过期的基准。
-
-### 2. CodeGraph 索引
-
-检查索引状态，**优先使用 MCP 工具**（若当前环境提供 `mcp__codegraph__codegraph_status` 则调用）；该工具不可用时**降级**为用 Glob 比对 `.codegraph/` 目录修改时间与最近提交时间。不允许通过普通 Bash 调 codegraph 命令：
-
-| 判断条件 | 状态 | 操作 |
-|----------|:----:|------|
-| 覆盖率 > 0% 且索引时间在最近提交之后 | ✅OK | 无需操作 |
-| 覆盖率 = 0% | ❌FAIL(未初始化) | 通过 PowerShell 执行 `npx @colbymchenry/codegraph && codegraph init --index` |
-| 索引时间在最近提交之前 | 🟡WARN(过期) | 同上 |
-
-> 前提：项目构建命令必须已成功。构建失败时先执行 `npx hunter-harness` 初始化检查。
-> 若 MCP 工具与 codegraph CLI 均不可用，标记 🟡WARN(CodeGraph 状态无法验证) 并在报告中说明"CodeGraph 状态无法验证，需用户手动确认"。
-
-### 3. harness-codebase-map 分析文档
-
-用 Glob 搜索 `.harness/codebase/map/*` 确认文件是否存在及其修改时间：
-
-| 判断条件 | 状态 | 操作 |
-|----------|:----:|------|
-| 文件存在且修改时间 < 7 天 | ✅OK | 无需操作 |
-| 超过 7 天 + 变更文件 > 10 个 | ❌FAIL(需要重建) | `/harness-codebase-map --fast` |
-| 超过 7 天 + 变更文件 ≤ 10 个 | 🟡WARN(可暂缓) | 提示用户，不强制更新 |
-| 文件不存在 | ❌FAIL(未初始化) | `/harness-codebase-map` |
-| 文件不存在 + CodeGraph 索引已最新 | 🟡WARN(可选) | 提示用户：CodeGraph 已覆盖代码智能，map 属可选重操作，由用户决定是否生成 |
-
-### 4. CLAUDE.md 完整性
-
-用 Read 读取 `CLAUDE.md`（或 `.claude/CLAUDE.md`），检查以下章节：
-
-| 必要章节 | 检测方式 | 缺失影响 |
-|----------|----------|----------|
-| 技术栈 | Read 后查找技术栈关键词（如框架/语言名称） | AI 可能建议不兼容的库 |
-| 构建命令 | Read 后查找 构建/编译 相关描述 | AI 不知道如何编译项目 |
-| 代码规范 | Read 后查找 分层/编码规范 相关描述 | AI 可能写出不符合项目约定的代码 |
-| 测试约定 | Read 后查找 test/测试/TDD 相关描述 | AI 不知道测试框架和命名规范 |
-| 架构约束 | Read 后查找 架构/分层/循环依赖/约束 相关描述 | AI 可能建议违反架构的设计 |
-| 行数 ≤ 200 | Read 后估算行数 | 超限 → 与用户确认瘦身策略，拆分到 `项目规则（见 .harness/context-index.json）/`。含 Skill 工作流说明的可放宽到 300 行 |
-
-**瘦身策略**：如果超过 200 行，不是简单截断——而是把可独立成篇的细节（如完整编码规范、详细架构图）迁移到 `项目规则（见 .harness/context-index.json）/` 下，CLAUDE.md 保留简洁的索引和关键命令。
-
-> ⚠️ CLAUDE.md 需要瘦身时，必须用 AskUserQuestion 与用户确认拆分方案后再执行。
-
-### 5. AGENTS.md 一致性
-
-检查 `AGENTS.md` 是否引用最新版 CLAUDE.md，是否包含项目概述和规则索引。如果 CLAUDE.md 刚刚更新过，同步更新 AGENTS.md 中的引用描述。
-
-### 6. .harness/ 完整性
-
-检查 `.harness/` 目录结构和配置文件。结构以产品 file-policy（`requirements/.../22-FILE-POLICY-MATRIX`）为准，init 实际产出的核心路径如下：
-
-| 检查项 | 判断条件 | 状态 | 操作 |
-|--------|----------|:----:|------|
-| 项目配置 | `.harness/project.yaml` 存在（user_editable，保存 project_id/server.url/token_env） | ✅OK | 无需操作 |
-| 路由索引 | `.harness/context-index.json` 存在（generated_reviewable） | ✅OK | 无需操作 |
-| 知识库 | `.harness/knowledge/index.json` 存在（user_editable） | ✅OK | 无需操作 |
-| state 目录 | `.harness/state/baseline/` 存在（internal_state） | ✅OK | 无需操作 |
-| codebase map | `.harness/codebase/map/` 状态 | — | 见第 3 步 |
-| 整体缺失 | `project.yaml` 与 `context-index.json` 均不存在 | ❌FAIL(未初始化) | 执行 `hunter-harness init`（见下方风险规程） |
-| .gitignore 选择性跟踪 | 未整条忽略 `.harness/`：user_editable（project.yaml/knowledge/）、generated_reviewable（codebase/map）多需跟踪；internal_state（state/）、generated_cache（cache/、generated/、reports/）不跟踪 | ✅OK | 无需操作 |
-| .gitignore 整体忽略 | `.gitignore` 含整条 `.harness/` | 🟡WARN(过度忽略) | 提示按 file-policy 拆分跟踪策略，而非整体忽略 |
-
-> ⚠️ **`hunter-harness init` 风险规程**（`.harness/` 未初始化时触发）：
-> 1. **预览**：`node packages/cli/dist/bin.js --non-interactive --dry-run --adapter claude-code --profile general --json`，确认将写入的路径清单与 `project_id`（`null` = 未绑服务器，本地自治理）。
-> 2. **备份**：将 `已安装 harness-* skills 目录（见 context-index）/`（尤其 `harness-*/SKILL.md`）、`CLAUDE.md`、`AGENTS.md` 复制到 `$env:TEMP/hh-init-backup-<时间戳>`。`.claude/` 若被 gitignore，被覆盖文件无 git 兜底，备份是唯一恢复途径。
-> 3. **执行**：`init --yes` 写入预览路径。
-> 4. **恢复**：逐个比对 `harness-*/SKILL.md` 与备份；被覆盖的从备份恢复，新增 skill（如 `harness-knowledge-ingest`、`harness-skill-optimizer`）保留。
-> 5. **验证**：`.harness/project.yaml`、`context-index.json` 就位；`CLAUDE.md`/`AGENTS.md` 的 managed block 为增量插入（原内容保留）。
->
-> file-policy 备注：`.harness/changes/**`（user_editable，push/update=never，本地工作材料）、`.harness/rules/**`（internal_state，本地默认不创建）都不作为完整性判断标志；旧文本的 `.harness/config/harness-test-config.md` 路径在产品中不存在，勿作检查项。
-
-### 7. 项目规则（见 .harness/context-index.json）/ 完整性
-
-用 Glob 搜索 `项目规则（见 .harness/context-index.json）/*.md`，检查是否覆盖 5 个必要主题：
-
-| 必要主题 | 检测方式 | 缺失影响 |
-|----------|----------|----------|
-| 架构规范 | 查找 framework/patterns/架构 相关文件 | AI 可能写出违反分层的代码 |
-| 编码规范 | 查找 coding-style/standards 相关文件 | AI 可能使用不一致的命名和注解 |
-| 数据库安全 | 查找 database-safety/sql 相关文件 | AI 可能执行危险的 DDL 操作 |
-| 测试约定 | 查找 test/validation/tdd 相关文件 | AI 可能不知道测试框架和命名规范 |
-| Git 提交 | 查找 git-commit/commit 相关文件 | AI 可能跳过确认直接提交 |
-
-> 缺失主题只提示用户补充，不自动创建规则文件。
-
-### 8. 构建配置健康度
-
-用 Read 读取项目构建配置文件（如 `.mvn/maven.config` 等）：
-
-| 检查项 | 判断条件 | 状态 | 操作 |
-|--------|----------|:----:|------|
-| 离线模式 | 包含 `-o` | 🟡WARN(离线模式) | 提示"离线模式可能导致依赖未缓存时构建失败，建议在 CLAUDE.md 中说明降级方案" |
-| settings 文件 | 包含 `-s` | ✅OK | 无需操作 |
-| 内容为空 | 无任何配置 | 🟡WARN(配置为空) | 提示"构建配置为空，可能缺少必要设置" |
-
-### 9. 测试基础设施
-
-用 Glob 搜索各模块的测试目录：
-
-| 判断条件 | 状态 | 操作 |
-|----------|:----:|------|
-| 模块有测试目录且含测试文件 | ✅OK | 无需操作 |
-| 模块有测试目录但无测试文件 | 🟡WARN(测试为空) | 提示"模块 X 测试目录为空，建议创建 SmokeTest" |
-| 模块无测试目录 | 🟡WARN(无测试目录) | 提示"模块 X 无测试目录，TDD 将降级为静态验证" |
-
-> 只检查有构建文件的业务模块，跳过 `*-client`、`*-sdk` 等纯接口模块。
-
-## 输出示例
-
-```markdown
-## 元数据同步报告 — `<service-module>`
-
-| 组件 | 状态 | 操作 |
-|------|:----:|------|
-| CodeGraph | 🟡WARN(索引过期) | 索引已过期（上次: 3天前，最近提交: 今天），已重新索引 |
-| harness-codebase-map (.harness/codebase/map/) | ✅OK | 2 天前更新，变更量 5 个文件，无需更新 |
-| CLAUDE.md | ✅OK | 180 行，6 个必要章节完整 |
-| AGENTS.md | ✅OK | 已正确引用 CLAUDE.md |
-| .harness/ | ✅OK | config 目录存在，1 个变更目录（contribution-module） |
-
-### 自动更新
-- CodeGraph 索引已重建，覆盖率 92%
-```
-
-## 关键原则
-
-- 先看 git log 了解变更量，再决定是否需要重建各组件（避免盲目全量重建）
-- CodeGraph 索引依赖编译产物，确保构建命令先通过
-- harness-codebase-map 和 Repomix 不要同时触发（两者都会产生大量上下文，叠加可能导致 API 输入超限）
-- CLAUDE.md 瘦身时，拆分到 `项目规则（见 .harness/context-index.json）/` 的文件必须有正确的 YAML frontmatter（含 `paths:` 字段）
-- **CLAUDE.md 需要瘦身时必须先与用户确认拆分方案**
-
-## 执行日志记录
-
-harness-sync 默认在控制台报告。检测到未归档变更时向 `events.ndjson` append `phase.start` / `phase.end` / `decision` / `issue`（`note` 含 10 项检查摘要）。见 SKILL.md `## 执行日志`。

package/resources/harness/bundles/java/codebuddy/harness-test/SKILL.md

@@ -1,172 +0,0 @@
----
-name: harness-test
-description: 测试执行：读取场景表，执行单元测试+API接口测试+数据兼容验证，输出测试报告。当用户说'跑测试/验证/跑用例/接口测试/单元测试'时使用
----
-<!-- generated by harness_deploy.py; core=c7f197c6a6f1ff5a; overlay=java; agent=codebuddy; do not edit -->
-# harness-test — 测试执行
-
-## Purpose
-
-读取测试场景表，逐条执行单元测试和接口测试，验证代码变更的正确性，输出测试报告。
-
-## When to Use
-
-当用户明确要求运行测试时触发。典型触发语："跑测试""验证""跑用例""接口测试""单元测试"。属于自动调用型 skill（未设 `disable-model-invocation`），默认经 `/harness-test` 显式调用。
-
-使用场景：
-- 完成 `/harness-run` 编码后，验证单元测试 + 接口测试 + 数据兼容
-- 修改公共模块 / 数据访问 / sql / 权限认证 / 接口层 / 数据契约 后需要真实接口验证
-- run 阶段 ledger 可复用时，跳过单元测试重跑，只补接口测试
-
-前置依赖：
-- `.harness/changes/<change-name>/plans/<change-name>-test-scenarios.md` 存在（测试真相源）
-- `/harness-run` 已完成，或 ledger 中有可复用的 unitTest 结果
-- 必须读取 `.harness/changes/<change-name>/meta/worktree.json`：`requested=true` 且 worktree 已创建 → 在 worktree 目录中执行测试；`requested=true` 但 worktree 不存在 → 停止，提示先修复 `harness-run`，不得静默回到主目录
-
-跳过场景：
-- 仅改了注释 / 格式化等非行为性清理，且 ledger `postTestClassification=NON_BEHAVIORAL_CLEANUP`，可复用已有 apiTest 结果，不必重跑
-
-## 统一读取协议
-
-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]]
-
-## Workflow
-
-### Phase 0：环境准备（主会话执行，需要交互确认）
-
-执行 各项强制环境检查 + **命令执行模式 preflight (0.1)**；只有首选执行器不可用时，才执行 fallback 执行器探测。
-
-- **Read `checklist.md`** — 各项检查详情 + 0.1 preflight + Playwright 探测 + 避坑规则指引
-- **失败处理**：任一项检查失败 → 终止流程并报告原因，用户确认修复后才能继续
-- 通过后进入 Phase 1
-
-### Phase 0.1：命令执行模式 preflight（⚠️ 必须在编译/启动服务/生成 runner 之前执行）
-
-`/harness-test` 高度依赖 PowerShell 与接口测试执行器。如果当前会话处于 Auto mode / 安全分类器降级 / PowerShell 被拒，会反复失败并错误降级到 Playwright MCP 逐条接口，造成长时间阻塞。**必须先做 4 项执行模式检查**（PowerShell 基础命令、执行器运行时可用性、构建工具可用性、安全分类器），将通过的 `executorPath` 写入 `.harness/changes/<change-name>/runtime/preflight.json`。
-
-任一硬停情况（安全分类器不可用 / Auto mode 拦截 / PowerShell 被拒 / 执行器或构建工具不可执行）→ 原文输出"❌ 命令执行模式不可用..."，不得继续编译/启动服务/生成执行器，不得盲目降级到 Playwright MCP。用户确认切换权限模式后**必须重新执行 0.1**，重试 ≤ 1 次。详见 `reference.md`「命令执行模式 preflight」。
-
-### Phase 0.2：fallback 执行器探测（仅在首选执行器不可用时执行）
-
-只有 0.1 通过但首选接口测试执行器不可用时才执行 0.2。如果 0.1 已确认执行器在 PowerShell 中可用，直接选择 **接口测试执行器**（Node runner 为一种实现，可按项目替换），不得继续探测或使用 Playwright MCP。
-
-严格优先级（不得颠倒）：接口测试执行器（默认首选，Node runner 为一种实现，可按项目替换为其他 HTTP 客户端）> PowerShell batch `.ps1`（首选不可用时降级）> Playwright MCP `browser_evaluate`（仅当 1+2 都不可用或用户明确选择）> curl + UTF-8 JSON body file（最后兜底）> 禁止直接用 curl 内联发送含中文 JSON body。
-
-> ⚠️ Playwright MCP `browser_evaluate` 不得替代执行器。执行器在 PowerShell 可用时，**禁止**使用 Playwright MCP 逐条执行接口测试——认证凭证是独立凭证，应读认证凭证缓存，由执行器直连本地 baseURL 发起请求。详见 `reference.md`「fallback 执行器探测」。
-
-### Phase 1-2：测试执行（默认主会话执行）
-
-**Phase 1 前先读 verification-ledger**：读取 `.harness/changes/<change-name>/evidence/verification-ledger.json`，判断是否可复用 run 阶段的 unitTest（见「关键规则·四」）。
-
-**默认在主会话执行**（不委派 subagent）：
-- 单元测试：可复用则跳过重跑；否则按技术栈执行测试命令
-- 接口测试：**强制批量执行器**，一次跑完全部场景，主会话只读 JSON
-
-### Phase 3：覆盖率总结 + 关门检查（主会话执行）
-
-读取测试报告，生成覆盖率总结，**执行关门检查**，包含：单元测试通过/失败/跳过计数、接口测试逐条结果+汇总+耗时、数据兼容验证汇总、败因分类（代码 Bug vs 测试脚本 vs 预存问题）、请求执行器及降级原因、关门检查 10 项（见「关键规则·十」）。
-
-### Java 测试环境补充
-
-- **preflight 0.1**：写入 `runtime/preflight.json` 的 `executorPath`/`mvnVersion` 等；Maven 可用性 `mvn -version` exit 0
-- **编译门禁**：测试前按 `build-profile.json` 的 `buildCommands.compile`；输出须含 `BUILD SUCCESS` 或 exit 0 证据
-- **条件 install**：worktree 首建或上游模块变更时按 profile 执行 `buildCommands.install`（非每次强制 `-am`）
-- **单元测试**：可复用 ledger unitTest 则跳过；否则 `buildCommands.unitTest`（典型 `mvn test -pl <module>`）
-- **服务启动**：`build-profile.json` 的 `serviceStartTemplate`（典型 `spring-boot:run` + profile）；**禁止 hardcode 端口/模块路径**
-- **服务指纹输入**（Task 3 §5.1）：`serviceStart.inputFiles` 必须列出 module 源 glob（如 `["<module>/pom.xml", "<module>/src/main/**/*.java", "<module>/src/main/resources/**"]`）；`harness_service.py ensure` 取 CLI `--files` ∪ `inputFiles` 计算 `moduleInputsHash`。**空输入被拒绝**，不得生成可复用空指纹。源码/command/profile/overlayPath 任一变化即 restart
-- **runtime overlay**：`-Dspring.config.additional-location=file:<ascii-abs-path>/application-harness-test.yml`；禁止默认 Edit tracked `application*.yml`
-- **known-good-test-profile**：profile 名、baseURL、healthUrl 写在 build-profile，非 skill 硬编码
-- **多租户请求头**：header 名/值来自 build-profile 的 `httpHeaders` 配置
-- **Service Gate**：`harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时**才** AskUserQuestion
-## 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]]
-
-## 关键规则（硬门禁速查）
-
-> 每条规则的详细判定、模板、表格见 `reference.md` 对应章节；Shell 执行安全见 `../protocols/powershell-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，ledger 见 `../protocols/ledger-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`，结构化报告事件见 `../protocols/report-pipeline-protocol.md`。
-
-### 一、接口测试工具优先级
-
-强制优先级：**接口测试执行器**（默认首选，Node runner 为一种实现，可按项目替换为其他 HTTP 客户端）> PowerShell batch `.ps1`（首选不可用时降级）> Playwright MCP `browser_evaluate`（仅 1+2 不可用或用户明确选择）> curl + UTF-8 JSON body file（最后兜底，须通过 PowerShell 调用）。**禁止裸 `node`、禁止用 Bash 执行 node**（`disallowed-tools` 已禁 `Bash(node *)`）；执行器在 PowerShell 可用时**不得**用 Playwright MCP 逐条执行。详见 `reference.md`「接口测试工具优先级」。
-
-### 二、批量测试执行 + Runner 三阶段
-
-0.1 通过后生成 `.harness/changes/<change-name>/runtime/api-test-runner.mjs`（按技术栈选择实现，Node runner 为一种实现，可按项目替换），通过**一次命令**（PowerShell + 执行器绝对路径）执行全部场景，输出 `api-test-results.json`，主会话只读 JSON。执行器必须按 **setup / test / cleanup** 三阶段：setup 失败时依赖场景标 🟡 BLOCKED，**不得用 null ID 继续请求**。绝对路径从 `runtime/preflight.json` 的 `executorPath` 读取，禁止 hardcode。详见 `reference.md`「批量测试执行器」「执行器三阶段模板」。
-
-### 三、请求体与测试数据
-
-请求体必须从数据契约 / 接口定义 / 真实样例生成，**禁止临场猜字段、禁止先跑失败接口再补**。测试数据用唯一前缀 `TEST_<change-name>_<timestamp>_<random>`；唯一约束字段必须随机或避让，避免冲突导致大面积 BLOCKED。详见 `reference.md`「请求体生成」「测试数据治理」。
-
-### 四、单元测试复用 + 写入 ledger
-
-Phase 1 前先读 `.harness/changes/<change-name>/evidence/verification-ledger.json`：run 的 unitTest 满足（diffHash 一致 + module/profile 一致 + scope 一致或更严格 + run 后无行为性修改 + run 跑了全量测试）则复用，否则重跑测试命令（按技术栈，如 `mvn test -pl <module>`）。Phase 1/2 完成后必须写回 ledger 的 `unitTest`/`apiTest` 项。详见 `checklist.md`「单元测试复用」、`../protocols/ledger-protocol.md`。
-
-### 五、命令与请求超时治理
-
-所有命令必须有「预期时长 + 超时上限」，超过预期必须输出一次状态行，**不得静默等待**。`durationMs > 10000` → 🟡 SLOW，`> 30000` → ❌ TIMEOUT_RISK。详见 `reference.md`「命令与请求超时治理」。
-
-### 六、服务启动 + 生命周期管理
-
-启动等待状态机：0–30s 每 2s 探测、30–120s 每 5s 探测、>120s 读日志判定；遇启动失败特征立即停。**Service Gate**：`harness_service.py ensure` 返回 `action=needs-user-decision`（用户自启服务占端口）时 **才** AskUserQuestion；AI 托管服务或端口空闲则自动继续，不询问。服务指纹（`moduleInputsHash`，来自 CLI `--files` ∪ `serviceStart.inputFiles`）+ `startCommandHash` + `profile` + `overlayPath` + 进程身份任一变化即 restart；**空输入被拒绝**，不生成可复用空指纹。测试结束默认清理 AI 启动的服务。详见 `reference.md`「服务决策门」。
-
-### 七、运行时配置叠加（不动 tracked 配置）
-
-禁止默认 Edit tracked 应用配置文件。默认运行时配置叠加（ASCII 绝对路径）；改 tracked 配置 → 默认拒绝，记 `decision` 事件（不 AskUserQuestion，报告 🟡 WARN）。详见 `reference.md`。
-
-### 八、Token 缓存与复用
-
-先读 `.harness/changes/<change-name>/runtime/credential-cache.json`（认证凭证缓存，按项目认证机制；token/SSO 为常见实现），本地轻量接口验证通过则复用，失败才走远程认证。接口测试执行器用 request context / 原生 HTTP 客户端直连本地 baseURL，**不得依赖浏览器当前页面 origin**。同一次流程内凭证刷新计数 > 1 → 🟡 WARN。**不得在报告/日志/对话总结中输出明文凭证**。详见 `reference.md`「认证凭证缓存与复用」。
-
-### 九、测试报告状态规则
-
-整体 ✅OK / 🟡WARN / ❌FAIL 三态；API 维度使用 `OK` / `PARTIAL` / `BLOCKED` / `NOT_RUN` / `FAIL` 五态。**不得把「5 PASS + 9 BLOCKED + 1 FAIL」写成 `apiTest=NOT_RUN`**，正确为 `apiTest=PARTIAL`。P0 场景 BLOCKED 不得仍 OK。详见 `reference.md`「结果分级规则」。
-
-### 十、关门检查（结束前强制执行）
-
-输出最终总结前必须执行 10 项：`git status --porcelain` / `git diff --stat` / `git diff --check`（失败→❌FAIL，必须 PowerShell-only）/ 明文敏感信息 / runtime 不提交 / 服务生命周期收尾 / 测试数据清理 / 执行器表完整 / 慢请求或超时 / 未清理+fallback+慢请求→至少 🟡WARN。详见 `checklist.md`「关门检查」、`reference.md`「关门检查」。
-
-### 十一、请求执行器 fallback 输出 + 性能统计
-
-报告必须区分四种执行器（接口测试执行器 / PowerShell batch / Playwright MCP browser_evaluate / curl），**不得笼统写"Playwright"**，不得把 "Playwright API 执行器" 与 "Playwright MCP browser_evaluate" 混写。报告必须含请求耗时统计表。详见 `reference.md`「请求执行器 fallback 输出」「输出格式」。
-
-## Output Format
-
-> 详细报告格式见 `reference.md` 的「输出格式」模板。
-
-测试报告保存到 `.harness/changes/<change-name>/reports/test/test-report-YYYYMMDD-HHmm.md`（时间戳区分多次运行），同时在控制台输出摘要。
-
-## 渐进披露
-
-- **Read `checklist.md`** 仅在 Phase 0 环境准备时 — 含 各项强制检查、0.1 命令执行模式 preflight、服务生命周期清单
-- **Read `reference.md`** 仅在执行接口测试时 — 含 API 测试执行方法、已知良好测试配置、运行时配置叠加、setup/test/cleanup 执行器模板、双格式错误码兼容
-- **Read `pitfalls.md`** 仅在遇到测试失败时 — 含所有踩坑规则（30 条，含 Bash 执行执行器 / 运行时配置叠加 / 唯一字段冲突 / 服务生命周期等）
-
-## 交互白名单
-
-本 skill **仅允许**以下 AskUserQuestion；其余默认值 + `decision` 事件：
-
-1. **Service Gate**：仅当 `harness_service.py ensure` 返回 `needs-user-decision`（用户进程占端口）时询问处理方式
-
-## 执行日志
-
-`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 边界保持最新。