hunter-harness 0.1.3 → 0.2.0

package/resources/harness/bundles/java/codebuddy/protocols/powershell-protocol.md

@@ -0,0 +1,181 @@
+---
+description: harness 全流程的 Windows/中文路径命令执行协议。所有 skill 在需要 git/构建命令/node/文件系统命令时按本协议执行。由原 harness-plan/shell-safety.md 合并而来。
+---
+
+# PowerShell Protocol
+
+> 本协议适用于所有 harness-skills（sync/codebase-map/plan/run/test/review/submit/archive）。Windows 中文路径项目中，Bash 工具会被 hook 拒绝（返回 `Denied: non-ASCII path in Bash`），且 Bash 在中文路径下经常超时。统一通过 `powershell.exe -NoProfile -Command "..."` 执行，规避路径编码问题。
+
+## 1. PowerShell-first 自动重试策略
+
+Claude **必须默认使用 PowerShell** 执行 git/构建命令/系统命令，不应先尝试普通 Bash。
+
+正确策略：
+
+1. **优先直接使用 PowerShell**：`powershell.exe -NoProfile -Command "<命令>"`
+2. 如果 Claude 意外使用了普通 Bash，并出现以下任一输出：
+   - `PreToolUse:Bash hook error`
+   - `Denied: non-ASCII path in Bash`
+   - `Use Write/Edit/PowerShell instead`
+3. **必须立即自动改用等价 PowerShell 命令重试一次**——不得中断流程，也不得推断成功
+4. 只有 PowerShell 重试也失败、被拒绝、超时、无有效输出、或 exit code 非 0，才停止当前阶段
+5. 停止时不得宣称成功，必须标记为 ❌FAIL 或 🟡WARN(状态未知)
+
+```
+❌ 错误：先尝试普通 Bash，被拒绝后中断流程并宣称"工作区干净"
+git status --porcelain  → 被拒 → 输出"工作区干净" ← 禁止
+
+✅ 正确：直接使用 PowerShell，或被拒后自动重试
+powershell.exe -NoProfile -Command "git -C '<项目路径>' status --porcelain"
+```
+
+只有 PowerShell 命令也失败时，才停止当前阶段并请求用户介入。
+
+## 2. 统一模板
+
+```powershell
+powershell.exe -NoProfile -Command "<command>"
+```
+
+复杂命令优先写成临时 `.ps1`，再执行：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".harness/changes/<change>/runtime/<script>.ps1"
+```
+
+## 3. 禁止普通 Bash
+
+如果当前路径包含中文、空格、非 ASCII 字符，或项目位于 Windows 路径（如 `C:\...`），**禁止使用普通 Bash 执行以下命令**：
+
+- `git`（任何子命令：log、diff、status、stash、pull、push、commit、add、worktree 等）
+- 构建命令（按技术栈：`mvn` compile/test/package、`npm` run build/test、`pytest` 等子命令）
+- `node`、`curl`
+- `mkdir`、`cp`、`mv`、`rm`、`touch`、`cat`、`sed`、`awk`（文件操作）
+- `find`、`ls`、`grep`（文件搜索）
+
+禁止 Bash here-doc、Bash command substitution、Bash 管道作为默认执行方式。
+禁止因 Bash 中没有 node/构建命令/git 就降级执行器；应改用 PowerShell 绝对路径。
+
+## 4. 优先使用内置工具
+
+文件读写、移动前验证、扫描**优先使用 Claude Code 内置工具**：
+
+| 操作 | 内置工具 | 替代 Bash 命令 |
+|------|----------|----------------|
+| 读取文件 | `Read` | `cat` |
+| 编辑文件 | `Edit` | `sed` |
+| 写入文件 | `Write` | `echo >` / `touch` |
+| 搜索文件 | `Glob` | `find` / `ls` |
+| 搜索内容 | `Grep` | `grep` |
+| 创建目录 | `Write`（写入目标文件时自动创建） | `mkdir -p` |
+| 移动文件 | `Read` + `Write` + 验证 | `mv` / `cp` |
+
+## 5. Git/构建命令 通过 PowerShell 执行
+
+所有 git/构建命令必须通过 `Bash(powershell.exe:*)` 调用 PowerShell 执行：
+
+```powershell
+# Git 命令示例
+powershell.exe -NoProfile -Command "git -C 'C:\CQ_PROJECT\贡献积分管理系统\udp' status"
+powershell.exe -NoProfile -Command "git -C 'C:\CQ_PROJECT\贡献积分管理系统\udp' diff --name-only"
+powershell.exe -NoProfile -Command "git -C 'C:\CQ_PROJECT\贡献积分管理系统\udp' log --oneline -10"
+
+# 构建命令示例（按技术栈；Java=mvn，前端=npm，Python=pytest）
+powershell.exe -NoProfile -Command "mvn compile -pl <module> -o -q"
+powershell.exe -NoProfile -Command "npm --prefix <module> run build"
+powershell.exe -NoProfile -Command "pytest <module>"
+```
+
+> **路径引用**：PowerShell 中路径必须用单引号或双引号包裹，避免中文路径解析错误。使用 `git -C "<路径>"` 指定项目目录。
+
+## 6. PowerShell 调用被拒绝时的处理
+
+如果 `powershell.exe` 或 `pwsh` 调用被 hook 拒绝，或返回无有效输出：
+
+- **必须停止当前阶段**，标记为 ❌FAIL 或 🟡WARN，不得宣称成功
+- **不得回退到普通 Bash**——这是硬性约束，不是建议
+- **不得在 PowerShell 重试失败后继续流程**——必须请求用户介入
+- 提示格式：`"Shell 命令执行失败：powershell.exe 调用被拒绝或无有效输出。请在终端手动执行：<命令>，完成后告诉我继续。"`
+
+## 7. 失败判定
+
+出现以下任一情况，当前阶段至少 `🟡WARN`，影响关键门禁时必须 `❌FAIL`：
+
+- `PreToolUse:Bash hook error` — **必须立即改用 PowerShell 等价命令重试**
+- `Denied: non-ASCII path in Bash` — **必须立即改用 PowerShell 等价命令重试**
+- `Denied: non-ASCII path in Bash. Use Write/Edit/PowerShell instead.` — **必须立即改用 PowerShell 等价命令重试**
+- `安全分类器暂时不可用` 且命令不可执行
+- PowerShell 重试后仍出现上述标志 → ❌FAIL，停止当前阶段
+- 非 0 exit code → ❌FAIL
+- 无有效 stdout → ❌FAIL（空输出 ≠ 无提交，先怀疑工具问题）
+- `internal error` / `timeout` / `Tool result missing` → ❌FAIL
+
+普通 Bash 被拒绝 = 必须 PowerShell 重试，不是成功，也不是最终失败。
+PowerShell 重试失败 = 当前阶段失败或未知，必须停止。
+
+## 8. 证据化成功结论
+
+所有"成功"结论必须绑定**明确证据**：
+
+| 结论 | 必须的证据 |
+|------|-----------|
+| 编译成功 | 构建工具输出包含构建成功证据（Java=`BUILD SUCCESS`；前端/Python 按各自工具成功标志） |
+| 拉取成功 | git 输出包含 `Already up to date.` 或实际 pull/push/commit 成功信息 |
+| 打包成功 | 构建产物通过 Glob 扫描产物目录实际确认存在（Java=`target/*.jar`；前端=`dist/`；Python=`dist/`） |
+| 推送成功 | git push 输出包含 `To <remote>` 和实际推送范围 |
+| 测试通过 | 测试命令输出包含测试通过证据（Java=`Tests run: N, Failures: 0`；前端/Python 按各自工具成功标志） |
+| exit code 0 | 命令返回 exit code 0 |
+
+> 构建工具的 quiet 模式（如 `mvn -q`）只能写 `exitCode=0，无错误输出`，不得把"无输出"改写成 `BUILD SUCCESS`。
+
+**没有证据 = 不成功。** 如果命令被拒绝、超时、或输出不含成功标志，必须标注"未知"或"失败"，不得推断成功。
+
+## 9. allowed-tools 配置规则
+
+Claude Code 不支持 `PowerShell(...)` 过滤语法，且 `allowed-tools` 不是严格白名单而是免确认通道。所有 skill 的 `allowed-tools` 使用以下策略实现 PowerShell-first：
+
+- **需要执行 git/构建命令的 skill**：`allowed-tools` 含 `Bash(powershell.exe:*)`（免确认通道），`disallowed-tools` 禁 `Bash(git *)`、`Bash(mvn *)`/`Bash(npm *)`/`Bash(pytest *)` 等裸命令（激活期间硬限制）
+- **不需要执行 git/构建命令的 skill**：不包含任何 Bash 工具
+- **codegraph 命令**：改为 MCP 工具调用（`mcp__codegraph__codegraph_*`），不再通过 Bash 调用
+- 不禁止 `Bash(powershell.exe:*)`——这是 PowerShell 调用的免确认通道
+- 所有 skill 正文中明确：Windows 或中文路径下，所有 git/构建命令/文件移动命令必须通过 `powershell.exe -NoProfile -Command "..."` 执行
+
+> 真正的强安全边界应结合 `permissions.deny`、`hooks`、`sandbox`；`allowed-tools`/`disallowed-tools` 只做激活期间预批准/限制。
+
+## 10. 各 skill 命令示例统一格式
+
+所有 skill 中的命令示例统一用 PowerShell 格式：
+
+```powershell
+# ❌ 旧格式（会被 hook 拒绝）
+git stash
+git pull origin master
+<构建命令> <模块定位参数>  # 例：mvn compile -pl <module> -o -q / npm --prefix <module> run build
+
+# ✅ 新格式（通过 PowerShell 执行）
+powershell.exe -NoProfile -Command "git -C '<项目路径>' stash"
+powershell.exe -NoProfile -Command "git -C '<项目路径>' pull origin <upstream-branch>"
+powershell.exe -NoProfile -Command "<构建命令> <模块定位参数>"  # 例：mvn compile -pl <module> -o -q
+```
+
+> 注意：构建命令（如 mvn）在 PowerShell 中通常不需要特殊处理（不含中文路径参数时可以直接执行），但为保持一致性，仍建议通过 powershell.exe 执行。
+
+## 11. 复杂 PowerShell 命令必须脚本化
+
+简单命令可以使用 `powershell.exe -NoProfile -Command "..."`。
+
+但如果命令包含以下内容，不得内联到 `-Command`：
+
+- `$variable`、`$_`、`$PSVersionTable` 等变量；
+- `@{}` hashtable；
+- `ForEach-Object` / `Where-Object` / script block `{ ... }`；
+- here-string；
+- 多管道和 JSON/HTML 大文本拼接。
+
+必须写入 `.harness/changes/<change>/scripts/*.ps1` 后使用：
+
+```powershell
+powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".harness/changes/<change>/scripts/<name>.ps1"
+```
+
+原因：Claude Code 的 Bash 工具外壳会先处理双引号内容，`$log`、`$_` 这类变量可能被外层 shell 吃掉，导致命令变形。简单命令可以 inline；复杂命令必须 `-File`。

package/resources/harness/bundles/java/codebuddy/protocols/report-pipeline-protocol.md

@@ -0,0 +1,150 @@
+---
+description: 结构化事件、summary-data 生成、final-summary 校验和外部可观测性边界协议（finalize/replay）。
+---
+
+# Report Pipeline Protocol
+
+## 核心原则
+
+最终报告分三层：
+
+1. **Event Layer**：`events.ndjson` 记录结构化执行事实。
+2. **Report Data Layer**：`summary-data.json` 由程序或确定性规则生成。
+3. **Renderer / Final Report Layer**：`final-summary.html` 只渲染和解释 summary-data，不重新推理统计。
+
+模型可以写维护者结论、风险解释和人工判断，但不得凭印象手写统计数字、通过率、耗时、命令结果或 artifact hash。
+
+## 标准命令
+
+Skill-bundled 脚本（推荐）：
+
+```powershell
+python <skills-root>/scripts/harness_archive.py finalize --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --json
+python <skills-root>/scripts/harness_archive.py replay --archive-dir ".harness/archive/YYYY-MM-DD-<change-name>" --json
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase "<phase>" --type <type> [--note "..."]
+```
+
+若项目安装 Hunter-Harness CLI，collect/validate 亦可使用（与 finalize 内嵌步骤等价）：
+
+```powershell
+powershell.exe -NoProfile -Command "npx hunter-harness report collect --change-id '<change-name>' --json"
+powershell.exe -NoProfile -Command "npx hunter-harness report validate --change-id '<change-name>' --json"
+```
+
+CLI 不可用时，agent 仍必须按本协议生成等价的 `summary-data.json` 并执行一致性校验，不得退回手写汇总。
+
+## events.ndjson
+
+**唯一实时日志源**。Harness skill 只向 `events.ndjson` 追加结构化事件；`logs/execution-log.md` 由 `harness_events.py` 渲染，**禁止手工 Edit**。
+
+事件文件位置：
+
+- 当前变更：`.harness/changes/<change-name>/events.ndjson`
+- 历史归档：`.harness/archive/<archive-name>/events.ndjson`
+
+写入方式：
+
+```powershell
+python <skills-root>/scripts/harness_events.py append --change-dir ".harness/changes/<change-name>" --phase "<phase>" --type <type> [--note "..."] ...
+```
+
+`append` 写入契约（Task 4 §6.1）：普通 append = 加锁 -> 追加一行 -> fsync -> 解锁，**不 load 历史、不渲染**（O(1)，跨进程锁 `events.ndjson.lock`，UUID 用完整 `uuid4().hex`）；仅 `--type phase.end` append 成功后渲染一次 `logs/execution-log.md`；显式 `harness_events.py render` 随时从完整 events 重建；`harness_archive.py finalize` 在 collect 前强制 render 一次。人类可读摘要（触发指令、降级原因、阶段结论）写入事件的 `note` 字段；阶段开始/结束、命令、验证、artifact、问题、决策各写对应 `type` 事件。旧 archive 缺少 events 可回放兼容；新变更不得以 execution-log 已存在为理由跳过 events。
+
+基础事件结构（schema_version 2）：
+
+```json
+{
+  "schema_version": 2,
+  "id": "evt-...",
+  "timestamp": "2026-07-02T00:00:00.000Z",
+  "phase": "run",
+  "type": "command",
+  "command": "npm test",
+  "exit_code": 0,
+  "duration_ms": 42100,
+  "note": "可选：触发指令、降级原因、阶段摘要"
+}
+```
+
+最低事件类型：
+
+| type | 必填/常用字段 | 用途 |
+|---|---|---|
+| `phase.start` | phase, timestamp | 阶段开始 |
+| `phase.end` | phase, timestamp | 阶段结束，计算耗时 |
+| `command` | command, exit_code, duration_ms | 命令事实 |
+| `verification` | name, status, command | 验证事实 |
+| `artifact` | path, kind | 报告、包、manifest 等产物 |
+| `issue` | code, severity, message | 问题和校验发现 |
+| `decision` | decision, reason | 人工确认、跳过、复用等决策 |
+
+## summary-data.json
+
+summary-data 必须保留原 archive final report 维度，并增加事件层摘要：
+
+```json
+{
+  "schemaVersion": "2.2",
+  "reportPipeline": {
+    "schema_version": 2,
+    "generated_at": "2026-07-02T00:00:00.000Z",
+    "event_count": 0,
+    "sources": ["events.ndjson", "evidence/verification-ledger.json"],
+    "phases": {},
+    "commands": [],
+    "verificationChecks": [],
+    "artifacts": [],
+    "validationIssues": []
+  }
+}
+```
+
+保留字段：
+
+- `businessGoal`
+- `finalStatus`
+- `diffStat`
+- `stageStatus`
+- `durations`
+- `skillCalls`
+- `verification`
+- `timeline`
+- `changedFiles`
+- `artifacts`
+- `reviewSummary`
+- `archiveManifest`
+- `uncommittedTestEvidence`
+- `maintenanceNotes`
+- `knownRisks`
+- `manualActions`
+
+新增 `reportPipeline` 不替代这些字段；它负责为这些字段提供可追溯的数据来源和一致性校验结果。
+
+## finalize 责任边界（`harness_archive.py finalize`）
+
+| 阶段 | 责任 | 写入 |
+|---|---|---|
+| `collect` | 从 events/ledger/log/manifest/report/git evidence 收集事实 | `summary-data.json` |
+| `render` | 由 `render-summary.mjs` 渲染 final-summary | `final-summary.html` |
+| `validate` | 检查 final-summary 是否覆盖 summary-data 关键事实 | issues；不得静默忽略 error |
+
+> **已废弃**：独立 `enrich` 步骤与 `harness-report` skill；全部并入 `finalize` 单命令。回放见 `harness_archive.py replay`。
+
+`validate` error 存在时，`harness-archive` 不得删除原 changes 目录。
+
+## 历史 archive 回放
+
+历史 archive 可能没有 `events.ndjson`。此时：
+
+- 不把缺少 events 当失败；
+- 从 `verification-ledger.json`、`execution-log.md`、`archive-manifest-*.json`、旧 `summary-data.json` 回放；
+- 在 `reportPipeline.sources` 中标明实际来源；
+- 对无法恢复的字段写 `unknown` / `not_available`，不得编造。
+
+## 外部平台边界
+
+当前本地流水线不接入 Langfuse、LangSmith、Temporal。
+
+- 可保留 `reportPipeline.externalTraceRefs[]` 等扩展字段。
+- 不得要求外部服务可用才允许 archive 成功。
+- 未来接入也必须以 `events.ndjson` 和 `summary-data.json` 为稳定合同，不改变 final-summary 质量维度。

package/resources/harness/bundles/java/codebuddy/protocols/sensitive-info-protocol.md

@@ -0,0 +1,92 @@
+---
+description: harness 全流程的敏感信息脱敏协议。所有 skill 的输出（控制台、execution-log、报告、commit message、final-summary）按本协议脱敏，禁止明文 token/密码/密钥。由原 harness-plan/sensitive-info.md 迁移。
+---
+
+# Sensitive Info Protocol
+
+> 本协议适用于所有 harness-skills 的输出（控制台、execution-log.md、package-report、review-report、final-summary.html、commit message）。
+
+## 1. 禁止明文输出的信息类型
+
+以下信息**不得以明文形式出现在任何输出中**：
+
+| 类型 | 示例 |
+|------|------|
+| Token / JWT | `eyJhbGciOi...`、`access_token=xxx` |
+| Authorization header | `Authorization: Bearer xxx` |
+| Cookie | `Cookie: session_id=xxx` |
+| 缓存凭证（如 Redis 密码） | `redis.password=xxx` |
+| 数据库凭证 | `jdbc:mysql://...?password=xxx` |
+| API key | `api_key=xxx`、`X-API-Key: xxx` |
+| Access key / Secret key | `accessKeyId=xxx`、`secretAccessKey=xxx` |
+| Jasypt 加密密钥 | `jasypt.encryptor.password=xxx` |
+| SSO 登录凭据 | `admin / admin123`（仅在开发环境说明中可用占位符） |
+| 任何含 `password`、`secret`、`token`、`key` 的字段值 | — |
+
+## 2. 脱敏替换规则
+
+如果用户贴出了敏感信息，后续引用时必须替换为以下占位符：
+
+| 原始内容 | 替换为 |
+|----------|--------|
+| Token 值 | `<TOKEN_REDACTED>` |
+| 密码值 | `<PASSWORD_REDACTED>` |
+| 密钥值 | `<SECRET_REDACTED>` |
+| API key 值 | `<API_KEY_REDACTED>` |
+| Authorization header 值 | `<AUTH_HEADER_REDACTED>` |
+| Cookie 值 | `<COOKIE_REDACTED>` |
+
+> 示例：
+> - 原始：`Authorization: Bearer eyJhbGciOiJIUzI1NiIs...`
+> - 替换：`Authorization: Bearer <TOKEN_REDACTED>`
+
+## 3. 禁止写入持久化文件
+
+以下文件中**不得包含任何明文敏感信息**：
+
+| 文件类型 | 路径示例 |
+|----------|----------|
+| 执行日志 | `.harness/changes/<change-name>/logs/execution-log.md` |
+| 审查报告 | `.harness/changes/<change-name>/reports/review/review-report-*.md` |
+| 测试报告 | `.harness/changes/<change-name>/reports/test/test-report-*.md` |
+| 最终总结 | `.harness/archive/YYYY-MM-DD-<change-name>/reports/final/final-summary.html` |
+| 归档元数据 | `.harness/archive/YYYY-MM-DD-<change-name>/meta/archive-meta.md` |
+| Commit message | git log 中的提交信息 |
+
+## 4. 命令示例使用占位符
+
+如需要给命令示例，使用占位符，不要复述真实值：
+
+```text
+# ❌ 禁止：复述真实 token
+curl -H "Authorization: Bearer eyJhbGciOi..." http://localhost:8083/api/...
+
+# ✅ 正确：使用占位符
+curl -H "Authorization: Bearer <TOKEN_REDACTED>" http://localhost:8083/api/...
+```
+
+```yaml
+# ❌ 禁止：复述真实密码
+spring:
+  datasource:
+    password: MySecretPass123
+
+# ✅ 正确：使用占位符
+spring:
+  datasource:
+    password: <PASSWORD_REDACTED>
+```
+
+## 5. 开发环境凭据的特殊处理
+
+项目默认凭据（如 `admin / admin123`）仅在以下场景允许出现：
+
+- 开发环境配置说明中（标注"仅供开发环境使用"）
+- 环境检查报告中的状态描述（标注"⚠️ 使用默认开发凭据"）
+
+但**不得出现在**：
+- execution-log.md
+- commit message
+- API 测试报告的持久化记录中
+
+> 对于 API 测试中获取的 token，在测试执行过程中可临时使用（如 Playwright 请求），但测试报告中必须用 `<TOKEN_REDACTED>` 替换。

package/resources/harness/bundles/java/codebuddy/protocols/state-layout-protocol.md

@@ -0,0 +1,131 @@
+---
+description: harness .harness 状态目录分层协议。用于减少根目录散乱、统一 archive 前后结构，并兼容旧路径。
+---
+
+# State Layout Protocol
+
+## 目标
+
+`.harness/changes/<change-name>/` 是变更状态真相源，但根目录不得继续堆放所有文件。新产物按子目录分层；旧路径保留读取兼容。
+
+## 推荐结构
+
+```text
+.harness/changes/<change-name>/
+├── meta/
+│   ├── change-context.json
+│   ├── worktree.json
+│   ├── manifest.json
+│   └── archive-meta.md
+├── logs/
+│   └── execution-log.md
+├── spec/
+├── plans/
+├── evidence/
+│   ├── verification-ledger.json
+│   └── run-task-status.md
+├── reports/
+│   ├── test/
+│   ├── review/
+│   ├── package/
+│   └── final/
+│       ├── summary-data.json
+│       └── final-summary.html
+├── sqls/
+├── scripts/
+├── runtime/
+│   └── service-session.json
+└── backups/
+    └── uncommitted-tests/
+```
+
+## service-session.json 与 serviceStart 契约
+
+`runtime/service-session.json`（由 `harness_service.py ensure` 写入）记录 AI 托管服务会话：`pid`、`startedBy`（`AI`/`User`）、`moduleInputsHash`、`moduleInputsFiles`、`profile`、`startCommandHash`、`overlayPath`、`command`、`startedAt`。
+
+服务复用（§5.3）必须**同时**比对 `moduleInputsHash` + `startCommandHash` + `profile` + `overlayPath` + 进程身份（pid 存活 + create time 匹配 `startedAt`）。任一变化 -> AI 自动 restart；身份无法确认 -> `needs-user-decision`；非 AI 用户进程永不自动 kill。
+
+`build-profile.json` 的 `serviceStart.inputFiles`（glob 列表，相对 project 展开）是 `moduleInputsHash` 的来源。`harness_service.py ensure` 取 CLI `--files` ∪ `serviceStart.inputFiles` 计算依赖闭包；**空输入被拒绝**（exit 非 0），**不得生成可复用的空指纹**。通用项目 detect 无法猜 module 源，`inputFiles` 默认空数组，须人工配置。
+
+## knowledge maintenance-outbox（§8）
+
+归档 close 不再同步执行知识维护；它写一个 pending outbox 项即返回：
+
+```text
+.harness/knowledge/maintenance-outbox/
+  pending/<archive-id>.json      # 待维护
+  running/<archive-id>.json      # maintain 正在处理
+  completed/<archive-id>.json    # 已完成（status=completed 或 completed_rules_pending_judge）
+  failed/<archive-id>.json       # 失败（attempts+1，可重试）
+```
+
+项 schema：`{schemaVersion, archiveId, archivePath, archiveManifestHash, status, attempts, createdAt, lastError, pendingJudgements?, completedAt?}`。
+
+`harness_knowledge.py maintain --project . --archive-id <id>` 单进程顺序：claim pending/failed -> running -> 增量 ingest（`build_index` 内含 in-memory near-dedupe，**不再二次磁盘 dedupe**）-> auto-supersede -> reverify-stale -> 导出残余 judge checklist -> running -> completed（或 `completed_rules_pending_judge` 若 `pendingJudgements>0`）。失败 -> failed（attempts+1，可重试）。completed 项重复 maintain 幂等。`harness-sync` 启动时扫描 pending/failed outbox 并执行 maintain。
+
+## 读取兼容
+
+所有 skill 读取状态时必须先读新路径，再兼容旧路径：
+
+| 类型 | 新路径 | 旧路径兼容 |
+|---|---|---|
+| execution log | `logs/execution-log.md` | `execution-log.md` |
+| ledger | `evidence/verification-ledger.json` | `verification-ledger.json` |
+| worktree | `meta/worktree.json` | `worktree.json` |
+| run status | `evidence/run-task-status.md` | `run-task-status.md` |
+| final summary data | `reports/final/summary-data.json` | `summary-data.json` |
+| final report | `reports/final/final-summary.html` | `final-summary.html` |
+
+## 写入规则
+
+新版本 skill 默认写新路径。为平滑迁移，允许同时在旧路径写一个简短指针文件，但不得再把大量产物堆在根目录。
+
+## change-context.json
+
+每个变更目录建议尽早写入：
+
+```json
+{
+  "changeName": "<change-name>",
+  "stateDir": ".harness/changes/<change-name>",
+  "logsDir": ".harness/changes/<change-name>/logs",
+  "evidenceDir": ".harness/changes/<change-name>/evidence",
+  "reportsDir": ".harness/changes/<change-name>/reports",
+  "scriptsDir": ".harness/changes/<change-name>/scripts",
+  "archiveTarget": ".harness/archive/YYYY-MM-DD-<change-name>"
+}
+```
+
+后续阶段应优先从该文件读取路径，避免手拼 change-name 导致路径拼写错误。
+
+## archive 结构
+
+archive 后保持同样分层结构，不把 `.bak`、脚本、manifest、HTML 全部放在 archive 根目录。
+
+未提交但用于验证的测试文件放入：
+
+```text
+backups/uncommitted-tests/
+```
+
+并在 `summary-data.json.uncommittedTestEvidence[]` 中说明。
+
+## 项目配置：`.harness/config/harness.json`
+
+Harness skill 读取的项目级配置（不提交 git）。缺失时使用下列默认值，**不得因缺失而阻断流程**——记 `decision` 事件说明使用了默认值。
+
+```json
+{
+  "defaultWorktree": false,
+  "knowledge": {
+    "manualReview": false
+  }
+}
+```
+
+| 字段 | 类型 | 默认 | 用途 |
+|------|------|------|------|
+| `defaultWorktree` | boolean | `false` | plan「设计审批包」中 worktree 推荐的预填值；用户可在审批包内覆盖 |
+| `knowledge.manualReview` | boolean | `false` | `true` 时 knowledge-ingest promote 等高价值操作需人工确认；`false` 时按 skill 默认策略 |
+
+读取顺序：`.harness/config/harness.json` → 缺失则默认值。plan 阶段 5 设计审批包须读取 `defaultWorktree` 作为 worktree 选项的推荐值。

package/resources/harness/bundles/java/codebuddy/protocols/submit-protocol.md

@@ -0,0 +1,78 @@
+---
+description: harness-submit 的确定性提交协议。用于避免 AskUserQuestion 参数错误、中文 commit message 失败、Co-Authored-By 违规和先 commit 后 amend。
+---
+
+# Submit Protocol
+
+## 交互模板固定化
+
+提交方式选择必须使用固定选项，不临场拼复杂参数：
+
+```text
+请选择提交方式：
+1. commit + push 到当前 upstream
+2. 仅本地 commit，不 push
+3. 取消提交
+```
+
+commit message 确认必须展示：staged 文件、diff stat、完整 commit message、是否 push。
+用户未明确确认前不得 commit。
+
+## commit message 文件流程
+
+中文 commit message 永远写入临时文件，再用 `git commit -F`：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' commit -F '.harness/changes/<change>/runtime/commit-message.txt'"
+```
+
+禁止：
+
+- 命令行内联长中文 message；
+- 先英文 commit 再 `git commit --amend` 成中文；
+- 使用 `--no-verify` / `--no-gpg-sign`；
+- 生成 `Co-Authored-By`、`Generated by`、`AI generated` 等 footer。
+
+## commit message 内容
+
+格式：
+
+```text
+<type>(<scope>): <中文摘要>
+
+- 变更点 1
+- 变更点 2
+
+验证：
+- <复用 ledger 或重跑验证摘要>
+```
+
+footer 默认为空。确需 issue footer 时必须由用户明确要求。
+
+## 远端检查
+
+push 前必须：
+
+```powershell
+powershell.exe -NoProfile -Command "git -C '<项目路径>' fetch"
+powershell.exe -NoProfile -Command "git -C '<项目路径>' log HEAD..@{u} --oneline"
+```
+
+远端有新提交时，不得直接 push。必须让用户选择：rebase 后重验 / 停止 push。
+
+## 提交状态映射
+
+submit 阶段的最终状态必须按以下映射落到三态标记，与 `evidence-based-reporting-protocol.md` 的 Git 操作状态对齐。不得用"提交成功"这类模糊表述，必须带状态标记和具体原因。
+
+| 提交结果 | 状态标记 | 报告表述 |
+|----------|:--------:|----------|
+| commit 成功且 push 成功（git push 输出含 `To <remote>` + 实际推送范围） | ✅OK | ✅OK 已提交并推送：commit `<hash>`，push 到 `<upstream>` |
+| 远端有新提交需 pull/rebase 后重验，或用户选择仅本地 commit 不 push | 🟡WARN(原因) | 🟡WARN(仅本地 commit，未 push) / 🟡WARN(远端有新提交，需 rebase 后重验) |
+| push 失败 / 被远端拒绝 / commit 失败 / pre-commit hook 拒绝 / exit code 非 0 | ❌FAIL(原因) | ❌FAIL(push 失败：`<原因>`) / ❌FAIL(commit 失败：`<原因>`) / ❌FAIL(hook 拒绝：`<原因>`) |
+
+说明：
+
+- **✅OK** 必须同时具备 commit 与 push 的成功证据；仅本地 commit 成功不算 ✅OK。
+- **🟡WARN** 是"提交动作完成但未达到完整推送"的中间态：用户主动选择仅本地 commit，或远端领先需 rebase。必须在原因中写明是"用户选择仅本地"还是"远端领先"。
+- **❌FAIL** 涵盖所有硬失败：push 被拒绝（含非 fast-forward 未处理）、commit 命令失败、hook 拒绝。出现时不得宣称"已提交"，必须停止并请求用户介入。
+- 与 `evidence-based-reporting-protocol.md` 的 Git 操作状态映射一致：`To <remote>` + 推送范围 → ✅；无输出/状态未知 → ❌；被 hook 拒绝 → ❌。