hunter-harness 0.1.2 → 0.2.0

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

@@ -0,0 +1,142 @@
+---
+description: harness-apidoc 的7步工作流详细步骤、接口提取规则和执行日志记录格式。仅在执行文档生成流程时读取。
+---
+
+# harness-apidoc 检查清单
+
+## 步骤 0：启动准备
+
+确定变更名：用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（**排除 `.harness/archive/*/`**），读取 frontmatter 提取 `change-name`。默认最多一个未归档变更；如有多个，优先取最近修改的，或询问用户。
+
+**检查 worktree**：读取 `.harness/changes/<change-name>/meta/worktree.json`（旧路径兼容根目录 `worktree.json`）：
+
+- `requested=true` 且 `worktreeRoot` 存在 → cd 到 `worktreeRoot`，确保读取 worktree 中最新代码
+- `requested=true` 但 worktree 不存在 → **停止并提示用户修复 worktree 状态，不得静默回到主目录**
+- `requested=false` 或文件不存在 → 在主目录执行
+
+不要用 `**` 通配符扫描 worktree（返回 100+ 无关文件）。
+
+**append `phase.start`**（`harness_events.py`；禁止手工 Edit `execution-log.md`）：
+
+```powershell
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase apidoc --type phase.start --note "<触发指令>"
+```
+
+## 步骤 1：识别变更范围
+
+读取变更计划文件，结合 `git diff --stat` 确定涉及的 Controller、VO、ErrorCode 文件。
+
+**⚠️ 必读：审查 logs/execution-log.md 中的后续修复记录**
+
+plan 文件是初始设计，代码可能在 review/test 阶段被修改。必须读取 `logs/execution-log.md` 中 plan 之后的条目（旧路径兼容根目录 `execution-log.md`；特别是 harness-review 和审查修复补充），关注：
+
+- 哪些方法被修改了实现逻辑（如硬编码改为枚举）
+- 哪些字段被新增/删除/重命名
+- 哪些行为发生了变更（如权限策略调整）
+
+在生成文档时，以**实际代码**为准，不以 plan 文件的伪代码为准。
+
+## 步骤 2：提取接口信息
+
+逐个读取变更涉及的 Controller 文件，提取：
+
+- **接口路径和方法**：从 `@RequestMapping`、`@GetMapping`、`@PostMapping` 等注解
+- **请求参数**：从方法签名和 `@RequestBody`、`@RequestParam`、`@PathVariable` 注解
+- **请求体结构**：从 SaveReqVO、PageReqVO 等请求 VO 的字段定义
+- **响应体结构**：从 RespVO、SimpleRespVO 等响应 VO 的字段定义
+- **校验规则**：从 VO 上的 `@NotNull`、`@NotBlank`、`@Size` 等校验注解
+- **错误码**：从 ErrorCodeConstants 或相关常量类
+
+用 CodeGraph 辅助探索调用链（Controller → Service → Mapper），理解接口的业务逻辑。
+
+**⚠️ 行为变更接口必须读 Service 实际实现**
+
+对于有行为变更的接口（如权限调整、返回值结构变更、查询逻辑修改），必须读取 Service 实现类的实际代码，不能仅依赖 plan 文件中的伪代码。
+
+重点验证：
+
+- `getMeta()` 等返回动态数据的接口 → 读实际返回值构造逻辑
+- 枚举/常量值 → 读实际枚举类源码，不从 plan 推断
+- 权限校验逻辑 → 读实际 Service 方法体
+
+**枚举值交叉验证**：数据字典中的枚举值必须从实际枚举类源码提取，不从 plan 文件的伪代码推断。如果 plan 中写 `new SceneMetaVO("1", ...)` 但实际代码用 `ProjectTypeEnum.DELIVERY.getCode()`，以实际代码为准。
+
+**codegraph 降级策略**：
+
+- `codegraph_search` 返回 0 结果时（新文件索引未同步），立即用 Grep 搜索
+- `codegraph_node` 遇到重名符号时（如多个 ErrorCodeConstants），用 `file` 参数指定文件名
+- 不要对同一符号重复调用 codegraph_node 超过 2 次，第 2 次仍不对则用 Read 直接读文件
+
+## 步骤 3：确定文档类型
+
+| 变更规模 | 文档类型 | 说明 |
+|----------|----------|------|
+| 新功能/新模块（5+ 新接口） | **完整接口文档** | 包含所有章节 |
+| 扩展已有接口（新增字段、修改逻辑） | **增量接口文档** | 只描述变更部分，注明与旧版本的差异 |
+| 小改动（1-2 个字段变更） | **增量接口文档** | 简要描述变更 |
+
+## 步骤 4：生成文档
+
+按照 `reference.md` 的7章节模板生成文档。关键要求：
+- 每个接口必须有：路径参数表、Query/请求体字段表、响应字段表
+- 响应示例必须包含完整 JSON
+- 字段表必须包含：字段名、类型、必填（请求）、说明
+- 校验规则写入字段表的「校验」列（如 `≤50字符`、`枚举`）
+- 枚举值必须列入「数据字典」章节，标注前端展示方式
+- 前端用法要写具体（不是"展示数据"，而是控件+联动）
+- 扩展接口必须描述行为变更（不只是字段变更）
+- 前端交互建议用表格：操作 → 接口 → 触发时机 → 交互效果
+- 兼容性说明用表格：场景 → 旧行为 → 新行为 → 前端处理
+- 错误码必须包含触发场景列
+- 从代码提取信息，不从需求文档猜测
+
+**⚠️ 前端影响分级标注（强制）**
+
+每个变更接口必须标注前端影响级别，让前端开发者一眼看出哪些需要改代码、哪些无需处理：
+
+| 标记 | 含义 | 前端动作 |
+|:----:|------|----------|
+| 🔴 **BREAKING** | 破坏性变更，前端不修改会报错或功能异常 | **必须修改**，优先处理 |
+| 🟡 **NEEDS-UPDATE** | 非破坏性变更，但前端需要适配才能使用新功能 | **建议修改**，否则无法使用新能力 |
+| 🟢 **TRANSPARENT** | 后端内部变更，前端无感，无需修改 | 无需处理，仅供了解 |
+
+**判定规则**：
+
+- 🔴 **BREAKING**：删除字段、字段类型变更、枚举值删除/变更、请求必填字段新增、响应结构变更、接口路径变更
+- 🟡 **NEEDS-UPDATE**：新增可选字段、新增可选参数、新增响应字段（前端可选渲染）、行为变更（如权限放开，前端可删除旧的 403 处理）
+- 🟢 **TRANSPARENT**：后端内部重构（如死代码删除、Mapper 优化）、性能优化、日志变更、注释变更
+
+**标注位置**：
+
+1. **接口变更概览表**：在「变更」列后增加「前端影响」列
+2. **扩展接口详情**：每个接口标题下方用 callout 标注
+3. **文档开头**：增加「前端改动清单」摘要章节
+
+**前端改动清单模板**（放在文档开头，接口变更概览之前）：
+
+```markdown
+## ⚡ 前端改动清单
+
+> 前端开发者请优先处理以下 🔴 BREAKING 项，其次处理 🟡 NEEDS-UPDATE 项。
+
+| 优先级 | 接口 | 改动点 | 前端动作 |
+|:------:|------|--------|----------|
+| 🔴 | `GET /indicator/meta` | `applicableScenes[].code` 值从数字改为枚举编码 | Select 组件 value 改用 `projectType` 字段 |
+| 🔴 | `POST /indicator/applicable` | 请求体 `sceneCode` 删除 | 改为传 `projectType` |
+| 🟡 | `GET /indicator/enabled` | 新增 `projectType` 过滤参数 | 可选适配，传入可筛选适用指标 |
+| 🟢 | `POST /indicator/list` | 后端自动 orgCode 过滤 | 无需处理，前端可删除传 orgCode 逻辑 |
+```
+
+## 步骤 5：保存文档
+
+用 Write 工具保存到 `.harness/changes/<change-name>/apidoc/<模块名>-前端接口文档-YYYY-MM-DD.md`。
+
+## 步骤 6：展示并确认
+
+展示文档摘要，询问用户是否满意。不满意 → 修改后重新保存。
+
+**append `phase.complete`**（`note` 含结果/摘要/文档路径）：
+
+```powershell
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase apidoc --type phase.complete --note "OK|WARN|FAIL — <摘要>"
+```

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

@@ -0,0 +1,233 @@
+---
+description: harness-apidoc 的文档7章节完整模板和增量接口文档差异说明。仅在生成文档需要参考模板结构时读取。
+---
+
+# harness-apidoc 参考 — 文档模板
+
+## 文档7章节完整模板
+
+```markdown
+# <模块名> — 前端接口文档
+
+> **版本**：V<N> ｜ **日期**：YYYY-MM-DD ｜ **变更**：<change-name>
+> **基础路径**：`/<模块路径>` ｜ **认证**：Bearer Token ｜ **Content-Type**：`application/json`
+
+---
+
+## ⚡ 前端改动清单
+
+> 前端开发者请优先处理以下 🔴 BREAKING 项，其次处理 🟡 NEEDS-UPDATE 项。
+
+| 优先级 | 接口 | 改动点 | 前端动作 |
+|:------:|------|--------|----------|
+| 🔴 | `GET /xxx/meta` | `code` 值从数字改为枚举编码 | Select 组件 value 改用 `projectType` 字段 |
+| 🔴 | `POST /xxx/applicable` | 请求体 `sceneCode` 删除 | 改为传 `projectType` |
+| 🟡 | `GET /xxx/enabled` | 新增 `projectType` 过滤参数 | 可选适配，传入可筛选适用数据 |
+| 🟢 | `POST /xxx/list` | 后端自动 orgCode 过滤 | 无需处理，前端可删除传 orgCode 逻辑 |
+
+> 影响级别：🔴 BREAKING（必须修改）｜ 🟡 NEEDS-UPDATE（建议修改）｜ 🟢 TRANSPARENT（无需处理）
+
+---
+
+## 一、接口变更概览
+
+| # | 方法 | 路径 | 说明 | 变更 | 前端影响 |
+|:--:|------|------|------|:----:|:--------:|
+| 1 | GET | `/xxx/meta` | 获取下拉选项 | 🆕 新增 | — |
+| 2 | POST | `/xxx/applicable` | 查询可用数据 | 🆕 新增 | — |
+| 3 | POST | `/xxx/list/{pageNum}/{pageSize}` | 分页查询（新增字段） | 📝 扩展 | 🟡 |
+| 4 | GET | `/xxx/{id}` | 详情（新增子表） | 📝 扩展 | 🟡 |
+| 5 | DELETE | `/xxx/{ids}` | 批量删除 | — 不变 | 🟢 |
+
+> 变更标记：🆕 新增 ｜ 📝 扩展 ｜ ❌ 删除 ｜ — 不变 ｜ ⚠️ 废弃
+> 前端影响：🔴 BREAKING ｜ 🟡 NEEDS-UPDATE ｜ 🟢 TRANSPARENT
+
+---
+
+## 二、新增接口
+
+### 2.1 <接口名称>
+
+> `GET /xxx/meta` ｜ 用途：获取下拉选项
+
+**路径参数**：无
+
+**Query 参数**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `type` | String | 是 | 选项类型（见数据字典） |
+
+**响应示例**：
+
+```json
+{
+  "code": 0,
+  "msg": "成功",
+  "data": [
+    { "label": "选项A", "value": "A" }
+  ]
+}
+```
+
+**响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data[].label` | String | 选项显示文本 |
+| `data[].value` | String | 选项值 |
+
+**前端用法**：`type` → 下拉选择控件数据源
+
+---
+
+### 2.2 <接口名称>
+
+> `POST /xxx/applicable` ｜ 用途：查询可用数据
+
+**请求体示例**：
+
+```json
+{
+  "keyword": "张三",
+  "status": "ENABLED"
+}
+```
+
+**请求字段**：
+
+| 字段 | 类型 | 必填 | 校验 | 说明 |
+|------|------|:----:|------|------|
+| `keyword` | String | 否 | ≤50字符 | 模糊搜索关键词 |
+| `status` | String | 否 | 枚举 | 状态过滤（见数据字典） |
+
+**响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data[].id` | Long | 数据ID |
+| `data[].name` | String | 数据名称 |
+| `data[].status` | String | 状态（见数据字典） |
+
+**前端用法**：
+- `keyword` → 搜索输入框，输入后实时查询
+- `status` → 筛选下拉框，选中后过滤结果
+
+---
+
+## 三、扩展接口详情
+
+### 3.1 <接口名称>（新增字段）
+
+> `POST /xxx/list/{pageNum}/{pageSize}` ｜ 变更：新增 `status` 查询条件 + 响应新增 `status` 字段
+
+> 🟡 **NEEDS-UPDATE**：前端可选适配新字段，不修改不影响现有功能
+
+**新增请求字段**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|:----:|------|
+| `status` | String | 否 | 状态过滤（见数据字典） |
+
+**新增响应字段**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `data.list[].status` | String | 状态值（见数据字典） |
+
+**行为变更**：分页结果默认按创建时间倒序（原为正序）
+
+---
+
+## 四、数据结构
+
+### VO 定义
+
+#### <VOName>（<用途>）
+
+```typescript
+interface <VOName> {
+  id: number;              // 数据ID
+  name: string;            // 数据名称
+  status: string;          // 状态（见数据字典）
+  createTime: string | null; // 创建时间，ISO 8601
+}
+```
+
+### 数据字典
+
+#### status — 状态
+
+| 值 | 说明 | 前端展示 |
+|------|------|------|
+| `ENABLED` | 启用 | 🟢 绿色标签 |
+| `DISABLED` | 禁用 | 🔴 红色标签 |
+
+#### type — 选项类型
+
+| 值 | 说明 |
+|------|------|
+| `A` | 类型A |
+| `B` | 类型B |
+
+---
+
+## 五、前端交互建议
+
+### <页面名称>
+
+| 操作 | 调用接口 | 触发时机 | 交互效果 |
+|------|----------|----------|----------|
+| 页面加载 | `GET /xxx/meta` | `onMounted` | 填充筛选下拉框 |
+| 搜索 | `POST /xxx/list` | 输入后防抖 300ms | 刷新表格数据 |
+| 查看详情 | `GET /xxx/{id}` | 点击行 | 弹出详情抽屉 |
+
+---
+
+## 六、兼容性说明
+
+| 场景 | 旧行为 | 新行为 | 前端处理 |
+|------|--------|--------|----------|
+| `status=null` 的历史数据 | 字段不存在 | 返回 `null` | 前端判空显示「未设置」 |
+| 旧版分页响应 | 无 `status` 字段 | 新增 `status` 字段 | 前端可选渲染，不阻塞 |
+
+---
+
+## 七、错误码速查表
+
+| 编码 | 常量 | 信息 | 触发场景 |
+|------|------|------|----------|
+| 1002001 | `XXX_NOT_FOUND` | 数据不存在 | 查询ID不存在 |
+| 1002002 | `XXX_STATUS_INVALID` | 状态不允许操作 | 状态流转违规 |
+```
+
+## 增量接口文档差异
+
+增量文档与完整文档结构相同，但：
+
+- **前端改动清单**：必须包含，放在文档开头，列出所有 🔴 和 🟡 项
+- **接口变更概览**：只列出有变更的接口，必须包含「前端影响」列
+- **新增接口**章节：只写新增的
+- **扩展接口详情**：每个接口只展示新增/变更字段，用注释标注 `// ========== 新增字段 ==========`
+- **前端影响标注**：每个扩展接口标题下方必须用 callout 标注影响级别：
+
+  ```markdown
+  > 🔴 **BREAKING**：请求体 `sceneCode` 字段已删除，前端必须改为传 `projectType`，否则接口无法正常工作
+
+  > 🟡 **NEEDS-UPDATE**：新增 `projectType` 可选参数，前端可选适配以使用筛选功能
+
+  > 🟢 **TRANSPARENT**：后端自动 orgCode 过滤，前端无需修改（可选删除旧的传 orgCode 逻辑）
+  ```
+
+- **审查修复标注**：如果接口在 review 阶段被修改，在扩展接口详情中添加标注：
+
+  ```markdown
+  > ℹ️ **审查修复**：此接口在 harness-review 阶段有以下修改：
+  > - `code` 值从硬编码数字改为 `ProjectTypeEnum` 枚举编码
+  > - 前端依赖 `code` 字段需同步更新
+  ```
+
+- **数据结构**：只写新增或变更的 VO 字段和数据字典
+- **兼容性说明**：重点描述旧数据如何兼容新字段 + 审查修复引入的 breaking change，每行标注影响级别
+- **错误码**：只列新增的错误码
+- **前端交互建议**：只描述受变更影响的页面和操作

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

@@ -0,0 +1,198 @@
+---
+name: harness-archive
+description: 归档所有变更产出（计划/测试报告/审查/SQL/API文档）到
+  .harness/archive/，含归档元数据和可视化最终总结。使用场景：归档、完成归档、收尾、打包产出物
+---
+<!-- generated by harness_deploy.py; core=9a7af3c66acaad35; overlay=java; agent=codex; do not edit -->
+# harness-archive — 变更归档
+
+## Purpose
+
+将 `.harness/changes/<change-name>/` 的所有产出移入 `.harness/archive/YYYY-MM-DD-<change-name>/`，生成归档元数据和可视化最终报告，释放工作区。
+
+## When to Use
+
+使用场景：
+
+- 用户说"归档 / 完成归档 / 收尾 / 打包产出物"。
+- submit 已推送、test/review 报告已就绪（或已明确标记跳过/未运行），需要封存变更产出。
+- 变更闭环最后一站，归档后从工作区移除 `.harness/changes/<change-name>/`。
+
+跳过场景：
+
+- 变更尚未 submit 推送（归档前 commit 必须已 push）。
+- 仍存在未结清的 test/review 验证（除非已明确标记 CONDITIONAL_OK）。
+
+自动调用边界：
+
+- 归档涉及移动/删除原变更目录，支持被其他 skill 调用，但调用前必须确保前置条件已满足；也支持用户显式 `/harness-archive` 调用。
+- 归档前确认是强制阻断检查点，用户拒绝 → 终止流程，不执行任何操作。
+
+## 前置条件
+
+- commit 已 push（`git log @{u}..HEAD` 输出为空）
+- **最终 hash 来源**：worktree 模式（`meta/worktree.json` requested=true）下读 ledger 的 `mergeFinalHash`（由 `/harness-submit` 合并段写入）；主目录模式读 submit 的 `final pushed hash`。当前 `git rev-parse HEAD` 须一致
+- test 报告存在或标记"跳过"；review 报告存在或标记"未运行 review"（review 不阻塞归档）
+
+## Inputs
+
+- `$ARGUMENTS`：变更名（可选，留空时 Glob `.harness/changes/*/plans/*-plan.md` 自动检测，排除 `.harness/archive/`）
+- 相关文件：`.harness/changes/<change-name>/logs/execution-log.md`、`.harness/changes/<change-name>/events.ndjson`、`evidence/verification-ledger.json`、各阶段 reports/
+
+## 统一读取协议
+
+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：读取规则和上下文
+
+1. 读取本文件。
+2. 按需读取 `reference.md`（归档流程、manifest、summary-data、final-summary 渲染、目录结构与最终状态规则）。
+3. 读取共用约束：
+   - `../protocols/archive-report-protocol.md`
+   - `../protocols/state-layout-protocol.md`
+   - `../protocols/powershell-protocol.md`
+   - `../protocols/sensitive-info-protocol.md`
+   - `../protocols/evidence-based-reporting-protocol.md`
+   - `../protocols/report-pipeline-protocol.md`
+4. 解析 `$ARGUMENTS`：留空时 Glob 自动检测未归档变更，排除 `.harness/archive/`。
+
+### Phase 1：确认归档对象（扫描未归档变更）
+
+用 Glob 搜索 `.harness/changes/*/plans/*-plan.md`（排除 `.harness/archive/`），展示变更概要。
+
+- **Read `checklist.md`** — 归档前检查项
+- 发现多个未归档变更 → 让用户选择或终止
+
+### Phase 2：确认归档 ⚠️ 强制阻断
+
+AskUserQuestion 让用户确认归档操作。**用户拒绝 → 终止流程，不执行任何操作。**
+
+- **Read `reference.md`** — 确认对话框的内容格式
+
+### Phase 3：执行归档
+
+1. append `phase.start` 事件。
+2. 运行 `python <skills-root>/scripts/harness_archive.py status --change-dir ".harness/changes/<change-name>" --json` 前置检查。
+3. 运行 `python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json`；读 JSON（移动、collect、render、validate、manifest 比对）。**finalize 不再同步执行知识维护**（§8.2）：它写一个 `pending` maintenance-outbox 项即返回，`knowledgeMaintenance=QUEUED`；写 outbox 失败时 `NOT_QUEUED`（warning，不回滚 archive，总状态 CONDITIONAL）。后续由 `harness-sync` / `harness_knowledge.py maintain` 异步推进 outbox。
+4. 模型补写 `meta/archive-meta.md` 的维护者结论 / knownRisks / manualActions（脚本占位字段）。
+5. append `phase.end` 事件。**finalize 失败或 validate 报错时不删除原目录**。
+
+- **Read `reference.md`** — finalize 输出字段、archive-meta 格式、CONDITIONAL_OK 规则
+- **Read `templates/summary-data-template.json`** — summary-data 数据结构
+- **Read `templates/render-summary.mjs`** — final-summary 渲染脚本（finalize 内嵌调用）
+
+### Phase 4：验证与提示
+
+验证归档目录完整 → 提示用户归档完成。
+
+- **Read `checklist.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]]
+
+## 关键规则（硬门禁速查）
+
+> 每条规则的详细判定、模板见 `reference.md` 对应章节；归档报告协议见 `../protocols/archive-report-protocol.md`，Shell 执行安全见 `../protocols/powershell-protocol.md`，敏感信息见 `../protocols/sensitive-info-protocol.md`，证据化报告见 `../protocols/evidence-based-reporting-protocol.md`，状态目录见 `../protocols/state-layout-protocol.md`。
+
+### 一、同一时间最多 1 个未归档变更
+
+扫描排除 `.harness/archive/`；多个未归档变更 → 让用户选择或终止，不批量归档。
+
+### 二、归档前确认是强制阻断检查点
+
+AskUserQuestion 确认；用户拒绝 → 终止，不执行任何操作。
+
+### 三、文件移动只用内置工具或 PowerShell
+
+移动用 Read+Write+验证 或 PowerShell；**禁止 Bash mv/cp/rm**。移动失败时不删除原目录，报错退出让用户手动处理。
+
+### 四、数据化归档门禁（先数据后渲染）
+
+必须通过 `harness_archive.py finalize` 生成 `reports/final/summary-data.json` 与 `final-summary.html` 并完成 validate；**禁止模型临场写 500+ 行 HTML**。统计数字只能来自 summary-data、events、ledger 或 manifest。详见 `../protocols/report-pipeline-protocol.md`、`../protocols/archive-report-protocol.md`、`reference.md`。
+
+### 五、manifest/checksum 必须存在
+
+归档前后生成 `evidence/archive-manifest-before.json` / `archive-manifest-after.json`（path/size/sha256），before/after 不一致时**不得删除原目录**。复杂 PowerShell 写入 `scripts/*.ps1` 后 `-File` 执行，禁止内联 `$` / `$_` / `@{}`。详见 `reference.md`。
+
+### 六、归档前确认四项（缺一不可）
+
+- commit 已 push（`git log @{u}..HEAD` 输出为空）
+- **final hash 来源**：worktree 模式（requested=true）下读 ledger `mergeFinalHash`（submit 合并段）；否则读 submit 日志 `final pushed hash`。当前 HEAD 须一致
+- test 报告存在，或标记"跳过"/"未运行测试"
+- review 报告：存在则作 📝ADVISORY 归档材料；不存在标记"📝ADVISORY：未运行 review"（review 不阻塞归档）
+
+### 七、verification-ledger 汇总状态
+
+归档前读 `evidence/verification-ledger.json`，提取各阶段 status、postTestClassification、复用关系，供 final-summary 真实展示状态演进。若 ledger 有 `postTestClassification`，final-summary 必须展示该分类及对应的复用/重测决策。
+
+### 八、final-summary 不得伪造且必须展示状态演进
+
+无测试报告 → 显示"未运行测试 / 静态验证"，不得 100% 通过率；无 review → "📝ADVISORY：未运行 review"。状态用 ✅OK / 🟡WARN / 🔁REUSED / 🔁RETESTED / 📝ADVISORY / 🧹NON_BEHAVIORAL_CLEANUP，复用前一阶段结果显示 🔁REUSED，**不得伪装成重新执行，不得无脑全绿**。
+
+**final-summary 必须产出**：Node 渲染器不可用/超时/exit 非 0/未产出文件时，`harness_archive.py` 自动用内置 Python fallback 渲染（含 changeName/finalStatus/commands/verification/changedFiles/archiveManifest/knownRisks/manualActions/maintenanceNotes，USER_SKIPPED/BLOCKED_BY_DBA/失败状态可见，全部 HTML 转义）。Node 与 Python fallback **都失败**时，finalize 立即恢复原 change 目录并 exit 非 0，**绝不归档一个没有 final-summary.html 的变更**。
+
+### 九、CONDITIONAL_OK 最终状态
+
+API 测试 `USER_SKIPPED` 或 DB 兼容 `BLOCKED_BY_DBA` 时，最终状态必须是 `CONDITIONAL_OK`，不能显示纯 `OK`。
+
+### 十、未提交测试文件归档
+
+未提交但用于验证的测试文件必须归档到 `backups/uncommitted-tests/` 并在 final-summary 中展示。
+
+### 十一、phase.start 事件前置
+
+阶段 0 之前必须先 append `phase.start` 事件（`harness_events.py append`）；不得等归档完成才补。归档后 events.ndjson 与自动渲染的 execution-log.md 一起移入 archive。
+
+### 十二、Shell 安全 / 敏感信息 / 证据化报告
+
+git 命令通过 `powershell.exe -Command "..."` 执行；archive-meta.md 和 final-summary.html 不得含明文 token/密码/密钥；归档报告必须区分 ✅真实成功 / 🟡跳过·静态验证 / ❌失败。
+
+## Output Format
+
+> 归档元数据格式见 `reference.md` 的 archive-meta 模板；最终报告由 `templates/summary-data-template.json` 数据结构 + `templates/render-summary.mjs` 固定脚本渲染。
+
+产出文件：
+
+- `.harness/archive/YYYY-MM-DD-<change-name>/meta/archive-meta.md` — 归档元数据
+- `.harness/archive/YYYY-MM-DD-<change-name>/events.ndjson` — 结构化事件层（新流程推荐；旧 archive 可缺失）
+- `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/summary-data.json` — 最终报告数据源
+- `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/final-summary.html` — 由 `render-summary.mjs` 渲染（Node 不可用或失败时由 `harness_archive.py` 内置 Python fallback 渲染）；**始终必须存在**，否则 finalize 恢复原 change 目录并 exit 非 0
+- `.harness/archive/YYYY-MM-DD-<change-name>/evidence/archive-manifest-before.json` / `archive-manifest-after.json` — 归档前后 manifest/checksum
+
+## 渐进披露
+
+- **Read `checklist.md`** 仅在 Phase 1 归档前检查和 Phase 4 验证时 — 含归档前检查项和归档后验证项
+- **Read `reference.md`** 仅在 Phase 0/2/3 时 — 含归档流程、archive-meta 格式、summary-data 字段说明、final-summary 渲染规则、目录结构与最终状态规则
+- **Read `reference.md`** 仅在 Phase 3 finalize 时 — summary-data、final-summary 校验与 archive-meta 补写
+- **Read `templates/summary-data-template.json`** 仅在 Phase 3 生成 `summary-data.json` 时 — 含最终报告数据结构
+- **Read `templates/render-summary.mjs`** 仅在 Phase 3 渲染 `final-summary.html` 时 — 固定 HTML 渲染脚本
+
+## 交互白名单
+
+**仅允许**归档确认（Phase 2 AskUserQuestion）；拒绝 → 终止，不执行任何移动。
+
+## 执行日志
+
+`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/codex/harness-archive/checklist.md

@@ -0,0 +1,52 @@
+---
+description: harness-archive 的归档前检查项和归档后验证项。仅在 Phase 1 检查和 Phase 4 验证时读取。
+---
+
+# harness-archive 检查清单
+
+## P0 数据化归档门禁
+
+归档遵循 `../protocols/archive-report-protocol.md`，门禁要点见 SKILL.md `## 关键规则` 四/五/九：
+
+- 先写 `reports/final/summary-data.json`，再渲染 `reports/final/final-summary.html`。
+- 归档前生成 `evidence/archive-manifest-before.json`，移动后生成 `archive-manifest-after.json`。
+- final-summary 的统计只能来自 summary-data 或 manifest。
+- before/after checksum 不一致时，不得删除原目录。
+- 默认渲染器 `templates/render-summary.mjs`（finalize 内嵌调用）。
+
+## 归档前检查（Phase 1）
+
+> ⚠️ **phase.start 前置**：在归档前检查的第一项前，必须先 append `phase.start` 事件（见 SKILL.md `## 执行日志`）。不得等归档完成才补。
+
+- [ ] 已 append `phase.start` 事件（`harness_events.py append --change-dir ".harness/changes/<change-name>"`）
+- [ ] 只有一个未归档变更目录（多个时终止或让用户选择）
+- [ ] 变更目录下有 plans/ 子目录（至少有计划文件）
+- [ ] `logs/execution-log.md` 存在（需要追加归档记录；新路径缺失时兼容根目录 `execution-log.md`）
+- [ ] 准备生成 `archive-manifest-before.json`（path/size/sha256）
+- [ ] 准备生成 `summary-data.json`（业务目标、阶段状态、验证、产物、维护者结论）
+- [ ] git status 无未提交的重要变更（归档应对应已提交的代码）
+- [ ] **commit 已 push**：`powershell.exe -Command "git -C '<项目路径>' log @{u}..HEAD --oneline"` 输出为空（无未推送提交）
+- [ ] **最终 hash 一致**：worktree 模式（requested=true）下读 `evidence/verification-ledger.json` 的 `mergeFinalHash`（submit 合并段写入），否则从 events/ledger 读取 `final pushed hash`，与当前 `git rev-parse HEAD` 比对
+- [ ] **test/review 报告状态确认**：
+  - ✅ `.harness/changes/<change-name>/tests/test-report-*.md` 存在 → 归档正常
+  - 🟡 不存在 → 必须在 archive-meta.md 和 final-summary.html 中标记"跳过测试"或"未运行测试"，不得伪造通过率
+  - ✅ `.harness/changes/<change-name>/reports/review/review-report-*.md` 存在（旧路径 `reviews/review-report-*.md` 兼容回退）→ 作为 📝ADVISORY 归档材料
+  - 📝 `.harness/changes/<change-name>/reports/review/fixback-*.md` 存在 → 随 review 报告一并归档；默认 advisory，除非 `strict-review-gate=true`
+  - 🟡 不存在但 `logs/execution-log.md` 有 harness-review 小节 → **review 已运行但未落盘**（harness-review `context:fork` 交接缝常见，见 `agent/case-candidates/2026-06-30-harness-review-forked-not-persisting-report.md`）：从 execution-log/会话补落盘到 `reports/review/review-report-YYYYMMDD-HHmm.md` 再归档，**不得误标"未运行 review"**（实际跑过）
+  - 🟡 不存在且 execution-log 无 review 小节 → 在 archive-meta.md 和 final-summary.html 中标记"📝ADVISORY：未运行 review"
+
+## 归档后验证（Phase 4）
+
+- [ ] `.harness/archive/YYYY-MM-DD-<change-name>/` 目录存在（通过 Glob 实际扫描确认）
+- [ ] 所有子目录（plans/, tests/, reviews/, sqls/）已完整移入（通过 Glob 实际扫描确认，不仅看预期路径）
+- [ ] before/after manifest 校验通过（排除 `logs/execution-log.md`——归档追加结束记录预期 sha256 变化；其他 moved 文件 sha256 必须一致，missing/mismatch=0）
+- [ ] archive-meta.md 已创建，frontmatter 字段完整
+- [ ] summary-data.json 已生成，且为合法 JSON
+- [ ] final-summary.html 已由 `templates/render-summary.mjs` 渲染生成
+- [ ] **final-summary.html 真实性检查**：
+  - 无测试报告时，`summary-data.json.verification.unitTests.status` / `summary-data.json.verification.apiTests.status` 必须标记为 `NOT_RUN`、`USER_SKIPPED`、`BLOCKED` 或 `STATIC_ONLY`，不得显示 100%
+  - 无 review 报告时，`summary-data.json.reviewSummary.status` 必须标记为 `ADVISORY_NOT_RUN`，不得显示 100%
+  - 跳过、复用、人工确认的部分必须明确标记，不伪装成 ✅
+  - final-summary.html 中不得残留 `{{...}}` 占位符
+- [ ] 原目录 `.harness/changes/<change-name>/` 已删除（仅在前面所有验证通过后）
+- [ ] .harness/ 下无残留未归档变更目录