@hunter-harness/workflow-harness 0.4.0 → 0.4.2

package/harness/bundles/java/pi/protocols/registry-governance-protocol.md

@@ -0,0 +1,31 @@
+# 容器仓库容量与生命周期治理协议
+
+适用于 TCR、GHCR 及其他按标签或版本计数的容器仓库。平台适配器负责读取真实库存和执行受控删除；通用内核只做容量判断、保护集合闭包与 dry-run 计划。
+
+## 构建前容量预检
+
+每次候选构建前必须提供当前版本数、计划新增数、配额和告警比例。若计划后超过配额，返回 `REGISTRY_VERSION_QUOTA_FULL` 并在构建前阻断；达到告警水位返回 `REGISTRY_VERSION_QUOTA_WARNING`。
+
+禁止先构建镜像、再依赖推送失败发现容量不足。
+
+## 保护集合
+
+保护标签至少包含：
+
+- 当前生产与上一生产；
+- 冻结候选、回滚窗口内候选；
+- release/evidence/TAT/smoke 收据引用的标签或 digest；
+- 运维显式 pin。
+
+保护标签解析出的 digest 必须加入保护 digest。共享 digest 被任一保护标签引用时，所有指向该 digest 的标签都进入保护集合，不能仅凭另一个标签较旧就删除。
+
+## 清理计划与执行
+
+1. 先调用 `planRegistryCleanup` 生成 `dryRun=true` 的结构化计划；
+2. 候选按创建时间与标签稳定排序，仅删除达到目标水位所需的最小数量；
+3. 若保护版本数量已超过目标水位，返回 `PROTECTED_VERSIONS_EXCEED_TARGET`，不扩大删除范围；
+4. 平台适配器执行前重新读取库存并核对计划 identity；
+5. 执行后重新查询版本数、受保护 digest 和剩余容量，写入最终收据；
+6. 通用内核不直接持有平台凭据，也不执行删除 API。
+
+通用容量与计划内核由 `@hunter-harness/core` 的 `assessRegistryCapacity` 和 `planRegistryCleanup` 提供。

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

@@ -0,0 +1,172 @@
+---
+description: 结构化事件、summary-data 生成与校验，以及外部可观测性边界协议（finalize/replay）。
+---
+
+# Report Pipeline Protocol
+
+## 核心原则
+
+最终报告分三层：
+
+1. **Event Layer**：`events.ndjson` 记录结构化执行事实。
+2. **Report Data Layer**：`summary-data.json` 由程序或确定性规则生成。
+3. **Platform View Layer**：Hunter Platform 读取 `summary-data.json` 并展示结果，不在本地保存重复报告。
+
+模型可以写维护者结论、风险解释和人工判断，但不得凭印象手写统计数字、通过率、耗时、命令结果或 artifact hash。
+
+## 标准命令
+
+Skill-bundled 脚本（推荐）：
+
+```powershell
+python <skills-root>/scripts/harness_archive.py execute --change-dir ".harness/changes/<change-name>" --archive-root ".harness/archive" --intent record-only --closure completed --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 "..."]
+```
+
+归档报告流水线的常规入口是 `execute`。它只采集一次状态并复用给内部 finalize；`collect` 与 `validate` 是 finalize 的内嵌同进程步骤，**不作为独立 CLI 暴露**（不存在 `report collect` / `report validate` 子命令）。`summary-data.json` 只能由 finalize（归档时）或 `replay`（回放时）生成；**禁止 agent 临场手写或拼装等价的 `summary-data.json`**。`harness_archive.py` 不可用时归档失败退出，不得退回手写汇总。
+
+## 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。
+
+**artifact 硬门禁（H-8）**：`--type artifact` **必须**带非空 `--path`（change 相对路径）。知识探索/预览类说明改用 `--type issue` 或 `--type decision`，禁止再用 `--kind informational` 伪装无 path 的 artifact。
+
+基础事件结构（schema_version 3；兼容读取 v1/v2）：
+
+```json
+{
+  "schema_version": 3,
+  "id": "evt-...",
+  "timestamp": "2026-07-02T00:00:00.000Z",
+  "phase": "run",
+  "type": "command",
+  "command": "npm test",
+  "exit_code": 0,
+  "duration_ms": 42100,
+  "run_id": "run-...",
+  "attempt": 1,
+  "executor_tool": "codex",
+  "executor_agent": "main",
+  "executor_model": "gpt-5",
+  "handoff_from_tool": "claude-code",
+  "handoff_reason": "continue implementation",
+  "note": "可选：触发指令、降级原因、阶段摘要"
+}
+```
+
+最低事件类型：
+
+| type | 必填/常用字段 | 用途 |
+|---|---|---|
+| `phase.start` | phase, timestamp | 阶段开始 |
+| `phase.end` | phase, timestamp, status | 阶段结束并记录 `OK/WARN/FAIL/BLOCKED`；计算当前 attempt 耗时 |
+| `phase.prepare.start` | phase, timestamp, attempt, trigger | 开始检查再次执行阶段的前置条件；不计入产品阶段 attempt |
+| `phase.prepare.end` | phase, timestamp, attempt, status | 记录准备已启动或受阻及单独耗时；`BLOCKED` 不改变旧产品轮次 |
+| `command` | command, exit_code, duration_ms | 命令事实 |
+| `verification` | name, status, command | 验证事实 |
+| `artifact` | path, kind | 报告、包、manifest 等产物 |
+| `issue` | code, severity, message | 问题和校验发现 |
+| `decision` | decision, reason | 人工确认、跳过、复用等决策 |
+
+## 事件语义与必填字段
+
+写入 `events.ndjson` 时按用途选 type；渲染侧会对缺失字段做 note 兜底，但写入侧仍应填齐语义字段。
+
+| type | 用途 | 必填 | 常见误用 |
+|------|------|------|----------|
+| `issue` | 需要跟进/影响结论的异常 | severity, message | 把信息性结论记成 issue（应使用 decision） |
+| `decision` | 决策/结论/知识引用 | note 或 decision+reason | - |
+| `verification` | 验证执行结果 | name, status | 漏 name 导致 "(unnamed)" |
+| `artifact` | 产物落盘 | path | 只传 note |
+| `command` | 命令执行 | command, exit_code | - |
+
+兼容提示（不失败、exit 0）：
+
+- `--type issue` 未传 `--severity` → 默认 `info` 并在 stderr 提示
+- `--type verification` 未传 `--name` 或 `--status` → stderr 提示，照常写入
+
+## summary-data.json
+
+summary-data 必须保留原 archive final report 维度，并增加事件层摘要：
+
+```json
+{
+  "schemaVersion": "2.2",
+  "reportPipeline": {
+    "schema_version": 1,
+    "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` 不替代这些字段；它负责为这些字段提供可追溯的数据来源和一致性校验结果。
+
+## execute 与 finalize 责任边界
+
+`execute` 负责一次性状态采集、自动门禁、准备耗时事件和对 finalize 的单次调用。常规调用者不得串行执行 `auto-gate`、`status`、`finalize`。finalize 负责正式归档尝试，并复用 execute 传入的预检结果。
+
+| 阶段 | 责任 | 写入 |
+|---|---|---|
+| `collect` | 从 events/ledger/log/manifest/report/git evidence 收集事实 | `summary-data.json` |
+| `validate` | 检查 summary-data 的身份、验证状态与事实是否一致 | issues；不得静默忽略 error |
+
+> **已废弃**：独立 `enrich` 步骤与 `harness-report` skill；报告生成并入 finalize，常规归档由 `execute` 调用。回放见 `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` 为稳定合同，不改变结构化报告的质量维度。

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

@@ -0,0 +1,110 @@
+---
+description: harness 全流程的敏感信息脱敏协议。所有 skill 的输出（控制台、execution-log、报告、commit message、summary-data）按本协议脱敏，禁止明文 token/密码/密钥。由原 harness-plan/sensitive-info.md 迁移。
+---
+
+# Sensitive Info Protocol
+
+> 本协议适用于所有 harness-skills 的输出（控制台、execution-log.md、package-report、review-report、summary-data.json、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/summary-data.json` |
+| 归档元数据 | `.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>` 替换。
+
+## 6. profile / 规则 / Markdown 凭据扫描
+
+> 本节讲的是**写入时**的内容卫生，与上传门禁是两回事。CLI 的发布扫描
+> （`harness-push` / 归档）默认策略是 `warn`：命中项打印后照常上传，用
+> `HUNTER_HARNESS_SENSITIVE_SCAN=block` 才恢复阻断、`=off` 完全关闭。
+> 门禁放行不等于内容可以带明文凭据——本节的要求始终成立。
+
+profile `build-profile.json`、规则文档、Skill Markdown **不得包含凭据明文值**（spec §3.4 凭据边界：配置只含 env key、cache path、角色，不含值）。发布前用 `harness-test/scripts/runtime-helpers.mjs` 的 `findCredentialValues(text)` 扫描：
+
+- 命中 `password/token/secret/accessKey/Authorization: Bearer/jdbc password=` 等明文值 → ❌FAIL，必须改为占位符 `<*_REDACTED>` 或 env 引用 `${ENV}` / `$ENV`。
+- 占位符 `<TOKEN_REDACTED>` 与 env 引用 `${TEST_TOKEN}` / `$DB_PASSWORD` 不报（credential 配置允许 env key）。
+
+```js
+import { findCredentialValues } from '<skills-root>/harness-test/scripts/runtime-helpers.mjs';
+const findings = findCredentialValues(fs.readFileSync('build-profile.json', 'utf8'));
+if (findings.length > 0) { /* ❌FAIL: 列出 line/code/snippet，改为 env key 或占位符 */ }
+```

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

@@ -0,0 +1,209 @@
+---
+description: harness .harness 状态目录分层协议。用于减少根目录散乱、统一 archive 前后结构，并兼容旧路径。
+---
+
+# State Layout Protocol
+
+## 升级与本地状态保护边界
+
+`.harness/archive/`、`.harness/changes/` 是 protected local roots。CLI init/configure/refresh/rules 操作前必须：
+
+1. 综合 project marker、adapter `.harness-build.json`、managed block、恢复事务和非空 `.harness` 判断 `absent / valid / partial / recovery-required`；
+2. 对 protected roots 记录文件数、目录数、字节数、Merkle root，以及 archive 首末 identity；
+3. 事务 journal 声明每个允许修改的路径；任何未声明的 protected-root mutation 立即回滚；
+4. partial 或 recovery-required 状态 fail closed，输出 sentinels、inventory 与恢复指引，禁止当成空项目自动 init。
+
+事务提交前后 protected inventory 必须一致；除非当前命令显式以该 protected root 为操作目标。删除 `project.yaml` 但保留 archive，或删除 `.harness` 但保留 adapter marker，均属于 partial state，不是首次安装。
+
+## 目标
+
+`.harness/changes/<change-name>/` 是变更状态真相源，但根目录不得继续堆放所有文件。新产物按子目录分层；旧路径保留读取兼容。
+
+## 双根布局（split-v1，2026-07 起）
+
+新 Change 将**静态合同**与**动态运行状态**分离到两个唯一所有者：
+
+```text
+.harness/changes/<change-name>/        # contractRoot：静态合同（spec/plans/meta）
+.harness/state/changes/<change-name>/  # stateRoot：动态状态（events/logs/ledger/tracking/reports/runtime）
+```
+
+- 合同由 `meta/change-context.json` 的 `stateOwnership.contractRoot` / `stateOwnership.runtimeRoot` 声明（schemaVersion 2）。
+- 动态产物（`events.ndjson`、`logs/execution-log.md`、`evidence/verification-ledger.json`、`evidence/test-tracking.json`、reports、runtime）只写 stateRoot。
+- 统一解析入口：`harness_paths.py` —— `resolve_change_layout()` 返回完整双根；`resolve_state_dir_for_contract()` 供 events/ledger/test_guard/gate 内部路由。
+- **legacy-colocated**：未声明 `stateOwnership` 的旧 Change 继续读写共址布局；resolve 只读，**绝不静默搬迁**；显式迁移须 copy → hash verify → atomic pointer switch。
+- 功能分支不得携带共享动态状态副本；checkpoint/archive 的 evidence snapshot 从 stateRoot 生成。
+
+## 推荐结构
+
+```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
+├── sqls/
+├── scripts/
+├── runtime/
+│   ├── service-session.json
+│   ├── run-sessions/<session-id>/
+│   │   ├── session.json
+│   │   ├── stdout.log
+│   │   └── stderr.log
+│   ├── environment-receipts/
+│   ├── invalidations/
+│   └── fixback/batches/
+└── 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` 默认空数组，须人工配置。
+
+过期的 service session 只有在进程身份明确不匹配时才允许由 `retire-stale` 移入
+`runtime/retired-service-sessions/`；该动作保留原始回执且不终止进程。受管命令、
+环境会话和 fixback 的完整合同见 `execution-session-protocol.md`。
+
+## 归档上传重试状态（§8）
+
+知识 ingest 由 Hunter Platform 在接收归档 ZIP 后执行，本地不再创建 `.harness/knowledge`
+或 maintenance-outbox。尚未被服务端确认持久化的包保存在：
+
+```text
+.harness/state/local/archive-packages/
+  <change-key>.zip              # 确定性核心归档包
+  <change-key>.upload.json      # 上传/失败收据（如存在）
+```
+
+ZIP 只包含 summary、spec、plans、archive-meta、change-context 和包 manifest。上传失败保留；
+每次 finalize 都先生成 ZIP 与对应回执，再按 `credentials.local.yaml` 或
+`project.yaml` 的 `server.url` + `server.token_env` 环境变量解析远端凭据。缺少凭据、
+网络失败、无效收据或知识状态为 `indexing`/`failed` 时均保留这两个按 change 命名的文件，
+因此可枚举 `*.upload.json` 独立重试，不会由后一次归档覆盖前一次。只有 CLI 已核对
+package SHA-256，且服务端同时确认 `archive_status=durable` 与
+`knowledge_status=ready` 时，才清理对应 ZIP 和回执。回执的 `uploadStatus` 为
+`pending|failed|ready`，`reasonCode` 使用 `ARCHIVE_UPLOAD_*` 或
+`ARCHIVE_KNOWLEDGE_*` 稳定错误码；`indexing` 必须映射为 `pending`，不得误报失败。
+远端知识查询失败不得创建本地 fallback。
+
+## 读取兼容
+
+所有 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` |
+
+## 写入规则
+
+新版本 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 导致路径拼写错误。
+
+## state-snapshot.json（cluster 3 §3.6）
+
+`meta/state-snapshot.json`（由 `harness_state.py` 写入）集中记录 project/worktree root、不可变 `changeBase`、当前 HEAD，以及 profile/rules/map/knowledge/diff 各段指纹与相关文件。Plan 首次捕获把当时 HEAD 写入 `changeBase`；run/test/review/submit/archive 刷新时只能更新当前 HEAD 和各段指纹。失效时由脚本刷新，**不得仅凭缓存跳过代码或验证门禁，也不得把后续 HEAD 覆盖为变更基线**。
+
+schema：
+
+```json
+{
+  "schemaVersion": 1,
+  "generatedAt": "<iso>",
+  "changeName": "<change-name>",
+  "changeBase": "<首次 Plan 捕获的 sha>",
+  "project": {"root": "<abs>"},
+  "worktree": {"root": "<abs>"},
+  "git": {"base": "<sha>", "head": "<sha>"},
+  "segments": {
+    "<segment>": {"fingerprint": "sha256:...", "files": ["..."], "capturedAt": "<iso>"}
+  }
+}
+```
+
+各段独立失效：`is_segment_stale(snapshot, segment, current_fingerprint)` 比较单段指纹；段不存在 → stale（需采集）。`refresh_segments(..., segments=["profile"])` 只重采受影响段，其他段保留原 capturedAt/fingerprint（缓存失效只重采受影响段）。`git.base` 是 `changeBase` 的兼容镜像，不是每次 capture 的 HEAD。
+
+segment 的文件集由调用方（各 skill）决定：`capture_snapshot(..., segment_files={"profile": [...], "rules": [...]})`。snapshot 只负责采集 + 比对 + 失效，不负责发现文件。git 段记录 base/head；diff 段指纹由调用方按需用 `harness_ledger.compute_diff_hash` 采集后填入 segment_files。
+
+## archive 结构
+
+archive 后保持同样分层结构，不把 `.bak`、脚本、manifest 或其他生成文件堆在 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 选项的推荐值。
+
+## 可恢复文件事务
+
+schema v3 事务在本地 `transactions/<transaction-id>/` 保存 journal、before snapshot、staged payload、after manifest 和小型 status 投影。journal 固定 project identity、执行器版本、目标 Bundle identity、ownership manifest hash、plan hash 与 snapshot digest。
+
+未完成事务同时镜像到用户级恢复根：
+
+```text
+${HUNTER_HARNESS_RECOVERY_ROOT:-~/.hunter-harness/recovery}/<project-path-hash>/transactions/<transaction-id>/
+```
+
+因此项目内 `.harness` 局部丢失后，`status` 仍可只读发现恢复项。`resume` 仅在 plan/snapshot/staged digest 与已完成操作的当前文件状态全部匹配时继续 pending operations；任一不匹配均 fail closed。`rollback` 在写回 before snapshot 前重新校验 snapshot digest。事务提交或回滚成功后删除用户级镜像；本地 committed 事务仍按保留策略提供显式回滚。

package/harness/bundles/java/pi/protocols/submit-protocol.md

@@ -0,0 +1,78 @@
+---
+description: harness-submit 的确定性提交协议。用于避免 blocking user confirmation 参数错误、中文 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 拒绝 → ❌。

package/harness/bundles/java/pi/protocols/verification-graph-protocol.md

@@ -0,0 +1,32 @@
+# 能力感知验证图协议
+
+Build Profile v3 用 `verificationGraph` 取代账本内的固定验证目标清单。项目可以声明后端、前端、浏览器、数据库、性能或发布候选等任意目标，同时保留统一的依赖、覆盖度和证据复用语义。
+
+## 目标合同
+
+每个目标必须声明：
+
+- `commandKey`：指向 `commands` 中的真实命令；
+- `dependsOn`：需要先完成的验证目标；
+- `requiredCoverage`：`incremental/module-am/module`；
+- `candidate`：是否为发布候选门禁；
+- `requiredCapabilities`：执行环境必须具备的能力。
+- `resourceLocks`：目标独占或共享的数据库、端口、浏览器、容器等资源身份；
+- `estimatedDurationSeconds`：供默认串行策略和进度显示使用，不作为虚构 ETA 的依据；
+- `reusePolicy`：允许复用时必须匹配的产品、环境、命令与覆盖身份。
+
+`candidateTarget` 必须引用已声明目标。未知目标、未知依赖、循环依赖、命令缺失都 fail closed。
+
+## 选择与执行
+
+1. 从显式请求目标开始；未显式请求时使用 `candidateTarget`。
+2. 展开完整依赖闭包并按拓扑顺序执行。
+3. 缺失能力不得静默跳过：目标记录 `CAPABILITY_MISSING`，依赖它的目标记录 `DEPENDENCY_BLOCKED`。
+4. 未进入闭包的目标是 `omitted`，与“执行失败”或“因能力阻断”分开报告。
+5. 账本记录目标定义的规范化 identity；依赖、覆盖度或能力声明变化后，旧证据必须失效。
+6. 候选目标即使自身命令可运行，也必须等待所有依赖和能力满足。
+7. ready 目标按 `resourceLocks` 分 wave；锁相交的目标不得并行。预计 ≥60 秒且未声明锁的目标默认归入 `harness:unclassified-heavy` 串行队列。
+8. code freeze 后产品 identity 漂移必须返回 `FROZEN_IDENTITY_DRIFT`；禁止在旧候选上补跑后声称覆盖新候选。
+9. 每个 `RUN / REUSE / SKIP / BLOCKED` 决策都必须带稳定 `reasonCode` 和解释；`REUSE` 还必须绑定现有证据 identity。
+
+JSON 合同见 `contracts/build-profile-v3.schema.json`；通用选择器为 `@hunter-harness/core` 的 `selectVerificationTargets`。